Memory Functions of the Pointer-Based 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 22.35 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 character 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.]

Figure 22.35. Memory functions of the string-handling library.

(This item is displayed on page 1095 in the print version)

Prototype	Description
void *memcpy( void *s1, const void *s2, size_t n )
	Copies n characters from the object pointed to by s2 into the object pointed to by s1. A pointer to the resulting object is returned. The area from which characters are copied is not allowed to overlap the area to which characters are copied.
void *memmove( void *s1, const void *s2, size_t n )
	Copies n characters from the object pointed to by s2 into the object pointed to by s1. The copy is performed as if the characters were first copied from the object pointed to by s2 into a temporary array, and then copied from the temporary array into the object pointed to by s1. A pointer to the resulting object is returned. The area from which characters are copied is allowed to overlap the area to which characters are copied.
int memcmp( const void *s1, const void *s2, size_t n )
	Compares the first n characters of the objects pointed to by s1 and s2. The function returns 0, less than 0, or greater than 0 if s1 is equal to, less than or greater than s2, respectively.
void *memchr( const void *s, int c, size_t n )
	Locates the first occurrence of c (converted to unsigned char) in the first n characters of the object pointed to by s. If c is found, a pointer to c in the object is returned. Otherwise, 0 is returned.
void *memset( void *s, int c, size_t n )
	Copies c (converted to unsigned char) into the first n characters of the object pointed to by s. A pointer to the result is returned.

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. 22.36 uses memcpy (line 17) to copy the string in array s2 to array s1.

---

Figure 22.36. Memory-handling function memcpy.

(This item is displayed on pages 1095 - 1096 in the print version)

 1 // Fig. 22.36: fig22_36.cpp
 2 // Using memcpy.
 3 #include 
 4 using std::cout;
 5 using std::endl;
 6
 7 #include  // memcpy prototype
 8 using std::memcpy;
 9
10 int main()
11 {
12 char s1[ 17 ];
13
14 // 17 total characters (includes terminating null)
15 char s2[] = "Copy this string";
16
17 memcpy( s1, s2, 17 ); // copy 17 characters from s2 to s1
18
19 cout << "After s2 is copied into s1 with memcpy,
"
20 << "s1 contains "" << s1 << '"' << endl;
21 return 0;
22 } // end main

 

 After s2 is copied into s1 with memcpy,
 s1 contains "Copy this string"

 

---

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, and 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 22.8

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. 22.37 uses memmove (line 16) to copy the last 10 bytes of array x into the first 10 bytes of array x.

Figure 22.37. Memory-handling function memmove.

 1 // Fig. 22.37: fig22_37.cpp
 2 // Using memmove.
 3 #include 
 4 using std::cout;
 5 using std::endl;
 6
 7 #include  // memmove prototype
 8 using std::memmove;
 9
10 int main()
11 {
12 char x[] = "Home Sweet Home";
13
14 cout << "The string in array x before memmove is: " << x;
15 cout << "
The string in array x after memmove is: "
16 << static_cast< char * >( memmove( x, &x[ 5 ], 10) ) << endl;
17 return 0;
18 } // end main

 

 The string in array x before memmove is: Home Sweet Home
 The string in array x after memmove is: Sweet Home Home

 

---

Function memcmp (Fig. 22.38, lines 19, 20 and 21) 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. 22.38. 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 stringE (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).]

Figure 22.38. Memory-handling function memcmp.

 1 // Fig. 22.38: fig22_38.cpp
 2 // Using memcmp.
 3 #include 
 4 using std::cout;
 5 using std::endl;
 6
 7 #include 
 8 using std::setw;
 9
10 #include  // memcmp prototype
11 using std::memcmp;
12
13 int main()
14 {
15 char s1[] = "ABCDEFG";
16 char s2[] = "ABCDXYZ";
17
18 cout << "s1 = " << s1 << "
s2 = " << s2 << endl
19 << "
memcmp(s1, s2, 4) = " << setw( 3 ) << memcmp( s1, s2, 4 )
20 << "
memcmp(s1, s2, 7) = " << setw( 3 ) << memcmp( s1, s2, 7 )
21 << "
memcmp(s2, s1, 7) = " << setw( 3 ) << memcmp( s2, s1, 7 )
22 << endl;
23 return 0;
24 } // end main

 

 s1 = ABCDEFG
 s2 = ABCDXYZ

 memcmp(s1, s2, 4) = 0
 memcmp(s1, s2, 7) = -1
 memcmp(s2, s1, 7) = 1

 

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 16 of Fig. 22.39 searches for the character (byte) 'r' in the string "This is a string".

---

Figure 22.39. Memory-handling function memchr.

 1 // Fig. 22.39: fig22_39.cpp
 2 // Using memchr.
 3 #include 
 4 using std::cout;
 5 using std::endl;
 6
 7 #include  // memchr prototype
 8 using std::memchr;
 9
10 int main()
11 {
12 char s[] = "This is a string";
13
14 cout << "s = " << s << "
" << endl;
15 cout << "The remainder of s after character 'r' is found is ""
16 << static_cast< char * >( memchr( s, 'r', 16 ) ) << '"' << endl;
17 return 0;
18 } // end main

 

 s = This is a string

 The remainder of s after character 'r' is found is "ring"

 

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 16 in Fig. 22.40 uses memset to copy 'b' into the first 7 bytes of string1.

Figure 22.40. Memory-handling function memset.

 1 // Fig. 22.40: fig22_40.cpp
 2 // Using memset.
 3 #include 
 4 using std::cout;
 5 using std::endl;
 6
 7 #include  // memset prototype
 8 using std::memset;
 9
10 int main()
11 {
12 char string1[ 15 ] = "BBBBBBBBBBBBBB";
13
14 cout << "string1 = " << string1 << endl;
15 cout << "string1 after memset = "
16 << static_cast< char * >( memset( string1, 'b', 7 ) ) << endl;
17 return 0;
18 } // end main

 

 string1 = BBBBBBBBBBBBBB
 string1 after memset = bbbbbbbBBBBBBB