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>