| C Standard Library |
|---|
|
C string handling refers to a group of functions implementing operations on strings in the C standard library. Various operations, such as copying, concatenation, tokenization and searching are supported.
The only support in the C programming language itself for strings is that the compiler will translate a quoted string constant in the source into a null-terminated string stored in static memory.
However the standard C library provides a large number of functions designed to manipulate these null-terminated strings. These functions are so popular and used so often that they are usually considered part of the definition of C.
Contents |
Strings in general refer to a contiguous sequence of characters terminated by and including the first null code. In C, there are two types of strings: string, which is sometimes also called byte string, and wide string.[1] Byte string contains bytes as code units, whereas wide string contains the type wchar_t as code units.
A common misconception is that a string is an array, because string literals are converted to arrays during the compilation (or translation) phase.[2] It is important to remember that a string ends at the first NUL byte. An array or string literal that contains a null byte before the last byte therefore contains a string, or possibly several strings, but is not itself a string.[3]
The term pointer to a string is used in C to describe a pointer to the initial (lowest-addressed) byte of a string.[1] As pointers are used to pass a reference to a string to functions in C, documentation (including this page) will often use the term string when correct notation is to say pointer to string.
The term length of a string is used in C to describe the number of bytes preceding the null code.[1] strlen is a standardised function commonly used to determine the length of a string.
C strings in general require that zero code is not used within a string: byte string must not contain the null byte (0x00), wide strings must not contain a zero-valued wchar_t. This means that byte strings can contain data encoded as ASCII or any ASCII extension. It is not possible to store encodings such as UTF-16 in byte strings, since a 16-bit code unit can contain either a high or low byte that is zero without being zero itself. The encodings that can be stored in wide strings are defined by the width of wchar_t. In most implementations, wchar_t is at least 16 bits, thus all 16-bit encodings, such as UCS-2 and UTF-16, can be stored. If wchar_t is 32-bits, 32-bit encodings such as UCS-4 and UTF-32 can be stored in addition to the 16-bit encodings. Note, however, that the fact that an encoding can be stored, does not mean that it is supported by the C library functions, which usually support only one particular implementation-defined encoding. This does not affect the functions that do not interpret the characters, such as wcscpy.
Variable-width encodings can be used in both byte strings and wide strings. String length and offsets are measured in bytes or wchar_t, not in "characters", which can be confusing to beginning programmers. UTF-8 and Shift JIS are often used in C byte strings. Truncating strings with variable length characters using functions like strncpy or strncat or their wide string equivalents can produce invalid sequences at the end of the string. This can be unsafe if the truncated parts are interpreted by code that assumes the input is valid.
Support for non-ASCII literals such as char foo[512] = "φωωβαρ";(UTF-8) or wchar_t foo[512] = L"φωωβαρ"; (UTF-16 or UTF-32) is implementation defined.[4] Some compilers will require entering all non-ASCII characters as \xNN sequences for each byte of UTF-8, and/or \uNNNN for each word of UTF-16.
Most of the functions that operate on C strings are defined in the string.h (cstring header in C++). Functions that operate on C wide strings are defined in the wchar.h (cwchar header in C++). These headers also contain declarations of functions used for handling memory buffers; the name is thus something of a misnomer.
Functions declared in string.h are extremely popular since, as a part of the C standard library, they are guaranteed to work on any platform which supports C. However, some security issues exist with these functions, such as buffer overflows, leading programmers to prefer safer, possibly less portable variants, of which some popular ones are listed here.
In historical documentation the term "character" was often used instead of "byte" for C strings, which leads many to believe that these functions somehow don't work for UTF-8. In fact all lengths are defined as being in bytes and this is true in all implementations, and these functions work as well with UTF-8 as with any other byte encoding. The BSD documentation has been fixed to make this clear, but POSIX, Linux, and Windows documentation still uses "character" in many places where "byte" or "wchar_t" is the correct term.
| Name | Notes |
|---|---|
NULL |
macro expanding to the null pointer constant; that is, a constant representing a pointer value which is guaranteed not to be a valid address of an object in memory. |
wchar_t |
type used for a code unit in a wide strings, usually either 16 or 32 bits. |
wint_t |
integer type that can hold any value of a wchar_t as well as the value of the macro WEOF. This type is unchanged by integral promotions. Usually a 32 bit signed value. |
mbstate_t |
contains all the information about the conversion state required from one call to a function to the other. |
| Byte string |
Wide string |
Description[note 1] | |
|---|---|---|---|
| String manipulation |
strcpy |
wcscpy |
copies one string to another |
strncpy |
wcsncpy |
writes exactly n bytes/wchar_t to a string, copying from given string or adding nulls | |
strcat |
wcscat |
appends one string to another | |
strncat |
wcsncat |
apponds no more than n bytes/wchar_t from one string to another | |
strxfrm |
wcsxfrm |
transforms a string according to the current locale | |
| String examination | strlen |
wcslen |
returns the length of the string |
strcmp |
wcscmp |
compares two strings | |
strncmp |
wcsncmp |
compares a specific number of bytes/wchar_t in two strings | |
strcoll |
wcscoll |
compares two strings according to the current locale | |
strchr |
wcschr |
finds the first occurrence of a byte/wchar_t in a string | |
strrchr |
wcsrchr |
finds the last occurrence of a byte/wchar_t in a string | |
strspn |
wcsspn |
finds in a string the first occurrence of a byte/wchar_t not in a set | |
strcspn |
wcscspn |
finds in a string the last occurrence of a byte/wchar_t not in a set | |
strpbrk |
wcspbrk |
finds in a string the first occurrence of a byte/wchar_t in a set | |
strstr |
wcsstr |
finds the first occurrence of a substring in a string | |
strtok |
wcstok |
splits string into tokens | |
| Miscellaneous | strerror |
N/A | generates and reports a string containing an error message derived from the given error code |
| Memory manipulation |
memset |
wmemset |
fills a buffer with a repeated byte/wchar_t |
memcpy |
wmemcpy |
copies one buffer to another | |
memmove |
wmemmove |
copies one buffer to another, possibly overlapping, buffer | |
memcmp |
wmemcmp |
compares two buffers | |
memchr |
wmemchr |
finds the first occurrence of a byte/wchar_t in a buffer | |
|
|||
mbtowc - converts the first multibyte character in a string to the matching wide characterwctomb - converts a wide character to the matching multibyte character The C standard library contains several functions for numeric conversions. They are all defined in the stdlib.h header (cstdlib header in C++).
atof - converts a string to a floating-point valueatoi, atol, atoll (C99/C++11) - converts a string to an integerstrtof(C99/C++11), strtod, strtold(C99/C++11) - converts a string to a floating-point valuestrtol, strtoll - converts a string to a signed integerstrtoul, strtoull - converts a string to an unsigned integermemccpy - SVID, POSIX - copies up to specified number of bytes between two memory areas, which must not overlap, stopping when a given byte is found[5]mempcpy - GNU - a variant of memcpy returning a pointer to the byte following the last written bytestrcat_s - ISO/IEC WDTR 24731 - a variant of strcat that checks for errors, such as the destination buffer being too small, before copyingstrcpy_s - ISO/IEC WDTR 24731 - a variant of strcpy that checks for errors, such as the destination buffer being too small, before copyingstrdup - POSIX - allocates and duplicates a stringstrerror_r - POSIX 1, GNU - a variant of strerror that is thread-safe. GNU version is incompatible with POSIX one.strlcpy - a variant of strcpy that truncates the copied string if the destination buffer is too small[6]strlcat - a variant of strcat that truncates the appended string if the destination buffer is too small[6]strsignal - POSIX:2008 - returns string representation of a signal code. Not thread safe[7]strtok_r - POSIX - a variant of strtok that is thread-safe[8]Despite the well-established need to replace strcat and strcpy with functions that do not overflow buffers, no accepted standard has arisen. Partly this is due to the mistaken belief by many C programmers that strncat and strncpy have the desired behavior (neither function was designed for this and the behavior and arguments are non-intuitive and often written wrong even by expert programmers[6]). Replacement functions which take the buffer length as an argument have been proposed, but have failed to become standards for political rather than technical reasons:
strcat_s and strcpy_s attracted considerable criticism because even though they are defined in the ISO/IEC WDTR 24731 standard, they are currently supported only by Microsoft Visual C++. Their behavior on error is so useless (and even destructive in the case of strcat_s) that actually using them in cases where it is unknown if the string will overflow the buffer is almost impossible. Warning messages produced by Microsoft's compilers suggesting programmers use these functions instead of standard ones have been speculated by some to be a Microsoft attempt to lock developers to its platform.[9][10]
The more popular strlcpy and strlcat have been criticised on the basis that they encourage use of C strings and thus create more problems than they solve[11] and for lacking documentation.[12] Consequently they have not been included in the GNU C library (used by software on Linux), although they are implemented in OpenBSD, FreeBSD, Solaris, Mac OS X, and even internally in the Linux kernel.