20.11. Memory Functions of the C String-Handling Library
The string-handling library functions presented in this section facilitate manipulating, comparing and searching blocks of memory. The functions treat blocks of memory as arrays of bytes. These functions can manipulate any block of data. Figure 20.41 summarizes the memory functions of the string-handling library. In the function discussions, “object” refers to a block of data. [Note: The string-processing functions in prior sections operate on null-terminated strings. The functions in this section operate on arrays of bytes. The null-character value (i.e., a byte containing 0) has no significance with the functions in this section.]
Fig. 20.41. Memory functions of the string-handling library.
The pointer parameters to these functions are declared void *. In Chapter 8, we saw that a pointer to any data type can be assigned directly to a pointer of type void *. For this reason, these functions can receive pointers to any data type. Remember that a pointer of type void * cannot be assigned directly to a pointer of any other data type. Because a void * pointer cannot be dereferenced, each function receives a size argument that specifies the number of characters (bytes) the function will process. For simplicity, the examples in this section manipulate character arrays (blocks of characters).
Function memcpy copies a specified number of characters (bytes) from the object pointed to by its second argument into the object pointed to by its first argument. The function can receive a pointer to any type of object. The result of this function is undefined if the two objects overlap in memory (i.e., are parts of the same object). The program of Fig. 20.42 uses memcpy (line 14) to copy the string in array s2 to array s1.
1 // Fig. 20.42: fig20_42.cpp
2 // Using memcpy.
3 #include <iostream>
4 #include <cstring> // memcpy prototype
5 using namespace std;
6
7 int main()
8 {
9 char s1[ 17 ] = {};
10
11 // 17 total characters (includes terminating null)
12 char s2[] = "Copy this string";
13
14 memcpy( s1, s2, 17 ); // copy 17 characters from s2 to s1
15
16 cout << "After s2 is copied into s1 with memcpy,
"
17 << "s1 contains "" << s1 << '"' << endl;
18 } // end main
After s2 is copied into s1 with memcpy,
s1 contains "Copy this string"
Fig. 20.42. Memory-handling function memcpy.
Function memmove, like memcpy, copies a specified number of bytes from the object pointed to by its second argument into the object pointed to by its first argument. Copying is performed as if the bytes were copied from the second argument to a temporary array of characters, then copied from the temporary array to the first argument. This allows characters from one part of a string to be copied into another part of the same string.
Common Programming Error 20.11
String-manipulation functions other than memmove that copy characters have undefined results when copying takes place between parts of the same string.
The program in Fig. 20.43 uses memmove (line 13) to copy the last 10 bytes of array x into the first 10 bytes of array x.
1 // Fig. 20.43: fig20_43.cpp
2 // Using memmove.
3 #include <iostream>
4 #include <cstring> // memmove prototype
5 using namespace std;
6
7 int main()
8 {
9 char x[] = "Home Sweet Home";
10
11 cout << "The string in array x before memmove is: " << x;
12 cout << "
The string in array x after memmove is: "
13 << static_cast< char * >( memmove( x, &x[ 5 ], 10 ) ) << endl;
14 } // end main
The string in array x before memmove is: Home Sweet Home
The string in array x after memmove is: Sweet Home Home
Fig. 20.43. Memory-handling function memmove.
Function memcmp (Fig. 20.44, lines 14–16) compares the specified number of characters of its first argument with the corresponding characters of its second argument. The function returns a value greater than zero if the first argument is greater than the second argument, zero if the arguments are equal, and a value less than zero if the first argument is less than the second argument. [Note: With some compilers, function memcmp returns -1, 0 or 1, as in the sample output of Fig. 20.44. With other compilers, this function returns 0 or the difference between the numeric codes of the first characters that differ in the strings being compared. For example, when s1 and s2 are compared, the first character that differs between them is the fifth character of each string—E (numeric code 69) for s1 and X (numeric code 72) for s2. In this case, the return value will be 19 (or -19 when s2 is compared to s1).]
1 // Fig. 20.44: fig20_44.cpp
2 // Using memcmp.
3 #include <iostream>
4 #include <iomanip>
5 #include <cstring> // memcmp prototype
6 using namespace std;
7
8 int main()
9 {
10 char s1[] = "ABCDEFG";
11 char s2[] = "ABCDXYZ";
12
13 cout << "s1 = " << s1 << "
s2 = " << s2 << endl
14 << "
memcmp(s1, s2, 4) = " << setw( 3 ) << memcmp( s1, s2, 4 )
15 << "
memcmp(s1, s2, 7) = " << setw( 3 ) << memcmp( s1, s2, 7 )
16 << "
memcmp(s2, s1, 7) = " << setw( 3 ) << memcmp( s2, s1, 7 )
17 << endl;
18 } // end main
s1 = ABCDEFG
s2 = ABCDXYZ
memcmp(s1, s2, 4) = 0
memcmp(s1, s2, 7) = -1
memcmp(s2, s1, 7) = 1
Fig. 20.44. Memory-handling function memcmp.
Function memchr searches for the first occurrence of a byte, represented as unsigned char, in the specified number of bytes of an object. If the byte is found in the object, a pointer to it is returned; otherwise, the function returns a null pointer. Line 13 of Fig. 20.45 searches for the character (byte) 'r' in the string "This is a string".
1 // Fig. 20.45: fig20_45.cpp
2 // Using memchr.
3 #include <iostream>
4 #include <cstring> // memchr prototype
5 using namespace std;
6
7 int main()
8 {
9 char s[] = "This is a string";
10
11 cout << "s = " << s << "
" << endl;
12 cout << "The remainder of s after character 'r' is found is ""
13 << static_cast< char * >( memchr( s, 'r', 16 ) ) << '"' << endl;
14 } // end main
s = This is a string
The remainder of s after character 'r' is found is "ring"
Fig. 20.45. Memory-handling function memchr.
Function memset copies the value of the byte in its second argument into a specified number of bytes of the object pointed to by its first argument. Line 13 in Fig. 20.46 uses memset to copy 'b' into the first 7 bytes of string1.
1 // Fig. 20.46: fig20_46.cpp
2 // Using memset.
3 #include <iostream>
4 #include <cstring> // memset prototype
5 using namespace std;
6
7 int main()
8 {
9 char string1[ 15 ] = "BBBBBBBBBBBBBB";
10
11 cout << "string1 = " << string1 << endl;
12 cout << "string1 after memset = "
13 << static_cast< char * >( memset( string1, 'b', 7 ) ) << endl;
14 } // end main
string1 = BBBBBBBBBBBBBB
string1 after memset = bbbbbbbBBBBBBB
Fig. 20.46. Memory-handling function memset.