9.16. String handling

Numerous functions exist to handle strings. In C, a string is an array of characters terminated by a null. In all cases, the functions expect a pointer to the first character in the string. The header <string.h> declares these functions.

9.16.1. Copying

The functions for this purpose are:

#include <string.h>

void *memcpy(void *s1, const void *s2, size_t n);
void *memmove (void *s1, const void *s2, size_t n);
char *strcpy(char *s1, const char *s2);
char *strncpy(char *s1, const char *s2, size_t n);
char *strcat(char *s1, const char *s2);
char *strncat(char *s1, const char *s2, size_t n);

memcpy

This copies n bytes from the place pointed to by s2 to the place pointed to by s1. If the objects overlap, the result is undefined. The value of s1 is returned.

memmove

Identical to memcpy, but works even for overlapping objects. It may be marginally slower, though.

strcpy

strncpy

Both of these copy the string pointed to by s2 into the string pointed to by s1, including the trailing null. Strncpy will copy at most n characters, and pad with trailing nulls if s2 is shorter than n characters. If the strings overlap, the behaviour is undefined. They return s1.

strcat

strncat

Both append the string in s2 to s1, overwriting the null at the end of s1. A final null is always written. At most n characters are copied from s2 by strncat, which means that for safety the destination string should have room for its original length (not counting the null) plus n + 1 characters. They return s1.

9.16.2. String and byte comparison

These comparison functions are used to compare arrays of bytes. This obviously includes the traditional C strings, which are an array of char (bytes) with a terminating null. All of these functions work by comparing a byte at a time, and stopping either when two bytes differ (in which case they return the sign of the difference between the two bytes), or the arrays are considered to be equal: no differences were found, and the length of the arrays was equal to the specified amount, or the null was found at the end of a string comparison.

For all except strxfrm, the value returned is less than, equal to or greater than zero depending on whether the first object was considered to be less than, equal to or greater than the second.

#include <string.h>

int memcmp(const void *s1, const void *s2, size_t n);
int strcmp(const char *s1, const char *s2);
int strncmp(const char *s1, const char *s2, size_t n);
size_t strxfrm(char *to, const char *from,
int strcoll(const char *s1, const char *s2);

memcmp

Compares the first n characters in the objects pointed to by s1 and s2. It is very dodgy to compare structures in this way, because unions or ‘holes’ caused by alignment padding can contain junk.

strcmp

Compares the two strings. This is one of the most commonly used of the string-handling functions.

strncmp

As for strcmp, but compares at most n characters.

strxfrm

The string in from is converted (by some magic), and placed wherever to points. At most maxsize characters (including the trailing null) are written into the destination. The magic guarantees that two such transformed strings will give the same comparison with each other for the user's current locale when using strcmp, as when strcoll is applied to the original two strings.

In all cases, the length of the resulting string (not counting its terminating null) is returned. If the value is equal to or greater than maxsize, the contents of *to is undefined. If maxsize is zero, s1 may be a null pointer.

If the two objects overlap, the behaviour is undefined.

strcoll

This function compares the two strings according to the collating sequence specified by the current locale.

9.16.3. Character and string searching functions

#include <string.h>

void *memchr(const void *s, int c, size_t n);
char *strchr(const char *s, int c);
size_t strcspn(const char *s1, const char *s2);
char *strpbrk(const char *s1, const char *s2);
char *strrchr(const char *s, int c);
size_t strspn(const char *s1, const char *s2);
char *strstr(const char *s1, const char *s2);
char *strtok(const char *s1, const char *s2);

memchr

Returns a pointer to the first occurrence in the initial n characters of *s of the (unsigned char)c. Returns null if there is no such occurrence.

strchr

Returns a pointer to the first occurrence of (char)c in *s, including the null in the search. Returns null if there is no such occurrence.

strcspn

Returns the length of the initial part of the string s1 which contains no characters from s2. The terminating null is not considered to be part of s2.

strpbrk

Returns a pointer to the first character in s1 which is any of the characters in s2, or null if there is none.

strrchr

Returns a pointer to the last occurrence in s1 of (char)c counting the null as part of s1, or null if there is none.

strspn

Returns the length of the initial part of s1 consisting entirely of characters from s1.

strstr

Returns a pointer to the first occurrence in s1 of the string s2, or null if there is none.

strtok

Breaks the string in s1 into ‘tokens’, each delimited by one of the characters from s2 and returns a pointer to the first token, or null if there is none. Subsequent calls with (char *)0 as the value of s1 return the next token in sequence, with the extra fun that s2 (and hence the delimiters) may differ on each subsequent call. A null pointer is returned if no tokens remain.

9.16.4. Miscellaneous functions

#include <string.h>

void *memset(void *s, int c, size_t n);
char *strerror(int errnum);
size_t strlen(const char *s);

memset

Sets the n bytes pointed to by s to the value of (unsigned char)c. Returns s.

strlen

Returns the length of the string s not counting the terminating null. This is a very widely used function.

strerror

Returns a pointer to a string describing the error number errnum. This string may be changed by subsequent calls to strerror. Useful for finding out what the values in errno mean.