The <cstring> header is a wrapper for 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...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...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.
Search for a byte
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 (converts to unsigned char). The return value is a pointer into the mem array of the first occurrence of c, or NULL if c is not present in the first n bytes of mem.
strchr function, wmemchr in <cwchar>
Compare memory
int memcmp(const void* s1, const void* s2, size_t n)
The memcmp function compares the first n bytes of s1 and s2. If all n bytes are equal, the return value is zero. Otherwise, the return value is positive if s1 is greater than s2 or negative is s1 in less than s2.
strcmp function, strncmp function, wmemcmp in <cwchar>
Copy memory
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.
memmove function, strcpy function, strncpy function, wmemcpy in <cwchar>
Copy possibly overlapping memory
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.
memcpy function, strcpy function, strncpy function, wmemmove in <cwchar>
Fill memory with a byte
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.
memcpy function, wmemset in <cwchar>
NULL pointer
#define NULL 0
The NULL macro expands to the integer 0, which represents a null pointer.
NULL in <cstddef>
Size type
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.
size_t in <cstddef>
Concatenate strings
char* strcat(char* dst, const char* src)
The strcat function concatenates src onto the end of dst. The src and dst arrays cannot overlap. The caller must ensure dst points to a region of memory that is large enough to hold the concatenated result, plus its null terminator.
strcpy function, strncat function, wcscat in <cwchar>
Search a string for a character
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, NULL is returned.
memchr function, strcspn function, strpbrk function, strrchr function, strspn function, wcschr in <cwchar>
Compare strings
int strcmp(const char* s1, const char* s2)
The strcmp function compares two null-terminated strings. If the strings are equal, the return value is zero. Otherwise, the return value is positive if s1 is greater than s2 or negative is s1 in less than s2. If one string is a prefix of the other, the longer string is greater than the shorter string.
memcmp function, strncmp function, wcscmp in <cwchar>
Compare strings using locale's collation order
int strcoll(const char* s1, const char* s2)
The strcoll function compares two null-terminated strings, interpreting the strings according to the LC_COLLATE category of the current locale. The return value is the same as that of strcmp.
strcmp function, wcscoll in <cwchar>, <clocale>
Copy a string
char* strcpy(char* dst, const char* src)
The strcpy function copies the null-terminated string src to dst. The caller must ensure 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.
memcpy function, strncpy function, wcscpy in <cwchar>
Count initial characters not in a span set
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.
strchr function, strpbrk function, strspn function, strstr function, wcscspn in <cwchar>
Retrieve error message text
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.
perror in <cstdio>
Compute length of a string
size_t strlen(const char* s)
The strlen function returns the length of the null-terminated string s.
wcslen in <cwchar>
Concatenate strings
char* strncat(char* dst, const char* src, size_t n)
The strncat function concatenates src onto 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 dst points to a region of memory that is large enough to hold the concatenated result, plus the null terminator. The return value is dst.
strcat function, wcsncat in <cwchar>
Compare strings
int strncmp(const char* s1, const char* s2, size_t n)
The strncmp function compares at most n characters of two null-terminated strings. If the strings are equal, the return value is zero. Otherwise, the return value is positive if s1 is greater than s2 or negative is s1 in less than s2. If one string is a prefix of the other, the longer string is greater than the shorter string.
memcmp function, strcmp function, wcsncmp in <cwchar>
Copy a string
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.
memcpy function, strcpy function, wcsncpy in <cwchar>
Locate a character in a span set
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 appears in str, strpbrk returns NULL.
strchr function, strcspn function, strspn function, wcspbrk in <cwchar>
Locate rightmost occurrence of a character
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.
memchr function, strchr function, wcsrchr in <cwchar>
Count characters in a span set
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.
strchr function, strcspn function, strpbrk function, wcsspn in <cwchar>
Find a substring
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.
strchr function, wcsstr in <cwchar>
Tokenize a string
char* strtok(char* str, const char* delimset)
The strtok function splits str into separate tokens, separated by one or more characters from delimset.
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 NULL. Because strtok saves str, you can have only one series of strtok calls 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 NULL. Otherwise, it saves a pointer to the first non-delimiter character as the start of 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 NULL as the first parameter, it starts searching for the next token at the same point where the previous search ended.
strcspn function, strpbrk function, strspn function, wcstok in <cwchar>
Transform a string for collation
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 (if dst is not NULL). 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.
At most n bytes are stored in dst, including the trailing null character. If dst is NULL, n can be 0.
The return value is the number of transformed characters written to dst.
strcmp function, strcoll function, <clocale>, wcsxfrm in <cwchar>