13.18 <cstring>

The <cstring> header is for the C++ version of the C standard <string.h> header, which declares string-handling functions.

The functions in this section fall into two categories, identified by the first three letters of the function name:

mem . . .

The mem functions operate on arbitrary chunks of memory, treating the memory as arrays of unsigned char. The caller must specify the size of each memory chunk.

str . . .

The str functions operate on null-terminated character arrays. Even though the function parameters are declared as type char, they are always interpreted as unsigned char when comparing two characters.

See also <cwchar> for wide character string functions.

Instead of using C-style, null-terminated character arrays, C++ code should use the string and wstring classes that are declared in the <string> header. C++ strings offer high performance, more flexibility, more safety, and greater ease of use. The char_traits class template in <string> also provides member functions for working with narrow and wide character arrays.

const void* memchr(const void* mem, int c, size_t n)

      void* memchr(      void* mem, int c, size_t n)

The memchr function searches the memory that mem points to, of size n bytes, for the byte whose value is c (converted to unsigned char). The return value is a pointer into the mem array to the first occurrence of c, or a null pointer if c is not present in the first n bytes of mem.

See Also

strchr function, find in <algorithm>, wmemchr in <cwchar>

int memcmp(const void* s1, const void* s2, size_t n)

The memcmp function compares the first n bytes of s1 and s2 as arrays of unsigned char. If all n bytes are equal, the return value is 0. Otherwise, the return value is positive if s1 is greater than s2 or negative if s1 is less than s2.

See Also

strcmp function, strncmp function, equal in <algorithm>, lexicographical_compare in <algorithm>, mismatch in <algorithm>, wmemcmp in <cwchar>

void* memcpy(void* dst, const void* src, size_t n)

The memcpy function copies n bytes from src to dst. If src and dst overlap, the results are undefined. The return value is dst.

If you copy the memory that contains any non-POD objects, the results are undefined. See Chapter 6 for more information about POD objects.

See Also

memmove function, strcpy function, strncpy function, copy in <algorithm>, wmemcpy in <cwchar>, Chapter 6

void* memmove(void* dst, const void* src, size_t n)

The memmove function copies n bytes from src to dst. The memory regions can overlap. The return value is dst.

If you copy the memory that contains any non-POD objects, the results are undefined. See Chapter 6 for more information about POD objects.

See Also

memcpy function, strcpy function, strncpy function, copy in <algorithm>, copy_backward in <algorithm>, wmemmove in <cwchar>, Chapter 6

void* memset(void* s, int c, size_t n)

The memset function fills the array s with n copies of c (converted to unsigned char). The return value is s.

See Also

memcpy function, fill_n in <algorithm>, wmemset in <cwchar>

#define NULL  . . .

The NULL macro expands to a null pointer constant. See <cstddef> for more information.

See Also

NULL in <cstddef>

typedef  . . .  size_t

The size_t type is the type of the result of the sizeof operator. It is an unsigned integral type. The exact type is implementation-defined.

See Also

size_t in <cstddef>

char* strcat(char* dst, const char* src)

The strcat function concatenates src onto the end of dst, overwriting the null byte that ends dst. The src and dst arrays cannot overlap. The caller must ensure that dst points to a region of memory that is large enough to hold the concatenated result, including its null terminator.

See Also

strcpy function, strncat function, wcscat in <cwchar>

const char* strchr(const char* s, int c)

      char* strchr(      char* s, int c)

The strchr function returns a pointer to the first occurrence of c (converted to unsigned char) in the null-terminated string s. If c does not appear in s, a null pointer is returned.

See Also

memchr function, strcspn function, strpbrk function, strrchr function, strspn function, wcschr in <cwchar>

int strcmp(const char* s1, const char* s2)

The strcmp function compares two null-terminated strings as arrays of unsigned char. If the strings are equal, the return value is 0. Otherwise, the return value is positive if s1 is greater than s2 or negative if s1 is less than s2. If one string is a prefix of the other, the longer string is greater than the shorter string.

See Also

memcmp function, strncmp function, wcscmp in <cwchar>

int strcoll(const char* s1, const char* s2)

The strcoll function compares two null-terminated strings, interpreting the strings according to the LC_COLLATE (defined in <clocale>) category of the current C locale. The return value is the same as that of strcmp.

See Also

strcmp function, wcscoll in <cwchar>, collate in <locale>, <clocale>

char* strcpy(char* dst, const char* src)

The strcpy function copies the null-terminated string src to dst. The caller must ensure that dst points to a region of memory that is large enough to hold the entire src string plus its null terminator. The return value is dst.

See Also

memcpy function, strncpy function, wcscpy in <cwchar>

size_t strcspn(const char* str, const char* spanset)

The strcspn function returns the number of characters at the start of str that are not in the string spanset. Thus, the c in its name means complement, that is, strcspn counts characters that are in the complement of the span set.

See Also

strchr function, strpbrk function, strspn function, strstr function, wcscspn in <cwchar>

char* strerror(int errnum)

The strerror function returns a pointer to an error message string that corresponds to the error number errnum. The message is the same as that printed by the perror function.

A program must not modify the array returned by strerror, and subsequent calls to strerror can overwrite the array.

See Also

perror in <cstdio>, <cerrno>

size_t strlen(const char* s)

The strlen function returns the length of the null-terminated string s, that is, the number of bytes that come before the null byte at the end of the string.

See Also

wcslen in <cwchar>

char* strncat(char* dst, const char* src, size_t n)

The strncat function concatenates src onto the end of dst, overwriting the null byte at the end of dst. At most, n characters are copied from src. A terminating null character is always appended to the end of dst. The caller must ensure that dst points to a region of memory that is large enough to hold the concatenated result, including the null terminator. The return value is dst.

See Also

strcat function, wcsncat in <cwchar>

int strncmp(const char* s1, const char* s2, size_t n)

The strncmp function compares at most n characters of two null-terminated strings as arrays of unsigned char. If the strings are equal, the return value is 0. Otherwise, the return value is positive if s1 is greater than s2 or negative if s1 is less than s2. If one string is a prefix of the other, the longer string is greater than the shorter string.

See Also

memcmp function, strcmp function, wcsncmp in <cwchar>

char* strncpy(char* dst, const char* src, size_t n)

The strncpy function copies at most n characters from the null-terminated string src to dst. If src is shorter than dst, null characters are appended to the end so that exactly n characters are always written to dst.

The return value is dst.

See Also

memcpy function, strcpy function, wcsncpy in <cwchar>

const char* strpbrk(const char* str, const char* spanset)

      char* strpbrk(      char* str, const char* spanset)

The strpbrk function searches str for any of the characters in spanset and returns a pointer to the first occurrence of such a character. If none of the characters in spanset appear in str, strpbrk returns a null pointer.

See Also

strchr function, strcspn function, strspn function, wcspbrk in <cwchar>

const char* strrchr(const char* str, int c)

      char* strrchr(      char* str, int c)

The strrchr function returns a pointer to the last (rightmost) occurrence of c (converted to unsigned char) in the null-terminated string s. If c does not appear in s, NULL is returned.

See Also

memchr function, strchr function, wcsrchr in <cwchar>

size_t strspn(const char* str, const char* spanset)

The strspn function returns the number of characters at the start of str that are in the string spanset.

See Also

strchr function, strcspn function, strpbrk function, wcsspn in <cwchar>

const char* strstr(const char* str, const char* substr)

      char* strstr(      char* str, const char* substr)

The strstr function returns the address in str of the first occurrence of substr or a null pointer if substr does not appear in str.

See Also

strchr function, wcsstr in <cwchar>

char* strtok(char* str, const char* delimset)

The strtok function splits str into separate tokens, separated by one or more characters from delimset. The contents of str are modified when each token is found.

To parse a string str, you must call strtok multiple times. The first time, pass str as the first parameter to strtok; for the second and subsequent calls, pass a null pointer. Because strtok saves str, only one series of strtok calls can be active at a time. Each call to strtok can use a different delimset.

The strtok function skips over initial delimiters, searching str for the first character that is not in delimset. If it reaches the end of the string without finding any token characters, it returns a null pointer. Otherwise, it saves a pointer to the first non-delimiter character as the start of the token. It then searches for the next delimiter character, which ends the token. It changes the delimiter character to a null character and returns a pointer to the start of the token. When strtok is called with a null pointer as the first parameter, it starts searching for the next token at the point where the previous search ended.

See Also

strcspn function, strpbrk function, strspn function, wcstok in <cwchar>

size_t strxfrm(char* dst, const char* src, size_t n)

The strxfrm function transforms the src string by converting each character to its collation order equivalent. The equivalent is copied into dst. Thus, after transforming two different strings with strxfrm, the transformed strings can be compared by calling strcmp to obtain the same result as calling strcoll on the original strings.

No more than n bytes are stored in dst, including the trailing null character. If n is 0, dst can be null.

The return value is the number of transformed characters written to dst.

See Also

strcmp function, strcoll function, wcsxfrm in <cwchar>, collate in <locale>, <clocale>