Draft 2002-06-14

<cstring>

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...
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.

memchr function

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.

See Also

strchr function, wmemchr in <cwchar>

memcmp function

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.

See Also

strcmp function, strncmp function, wmemcmp in <cwchar>

memcpy function

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.

See Also

memmove function, strcpy function, strncpy function, wmemcpy in <cwchar>

memmove function

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.

See Also

memcpy function, strcpy function, strncpy function, wmemmove in <cwchar>

memset function

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.

See Also

memcpy function, wmemset in <cwchar>

NULL macro

NULL pointer

#define NULL 0

The NULL macro expands to the integer 0, which represents a null pointer.

See Also

NULL in <cstddef>

size_t type

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.

See Also

size_t in <cstddef>

strcat function

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.

See Also

strcpy function, strncat function, wcscat in <cwchar>

strchr function

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.

See Also

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

strcmp function

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.

See Also

memcmp function, strncmp function, wcscmp in <cwchar>

strcoll function

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.

See Also

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

strcpy function

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.

See Also

memcpy function, strncpy function, wcscpy in <cwchar>

strcspn function

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.

See Also

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

strerror function

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.

See Also

perror in <cstdio>

strlen function

Compute length of a string

size_t strlen(const char* s)

The strlen function returns the length of the null-terminated string s.

See Also

wcslen in <cwchar>

strncat function

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.

See Also

strcat function, wcsncat in <cwchar>

strncmp function

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.

See Also

memcmp function, strcmp function, wcsncmp in <cwchar>

strncpy function

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.

See Also

memcpy function, strcpy function, wcsncpy in <cwchar>

strpbrk function

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.

See Also

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

strrchr function

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.

See Also

memchr function, strchr function, wcsrchr in <cwchar>

strspn function

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.

See Also

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

strstr function

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.

See Also

strchr function, wcsstr in <cwchar>

strtok function

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.

See Also

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

strxfrm function

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.

See Also

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