Node:String/Array Conventions, Next:String Length, Previous:Representation of Strings, Up:String and Array Utilities

String and Array Conventions

This chapter describes both functions that work on arbitrary arrays or blocks of memory, and functions that are specific to null-terminated arrays of characters and wide characters.

Functions that operate on arbitrary blocks of memory have names beginning with mem and wmem (such as memcpy and wmemcpy) and invariably take an argument which specifies the size (in bytes and wide characters respectively) of the block of memory to operate on. The array arguments and return values for these functions have type void * or wchar_t. As a matter of style, the elements of the arrays used with the mem functions are referred to as "bytes". You can pass any kind of pointer to these functions, and the sizeof operator is useful in computing the value for the size argument. Parameters to the wmem functions must be of type wchar_t *. These functions are not really usable with anything but arrays of this type.

In contrast, functions that operate specifically on strings and wide character strings have names beginning with str and wcs respectively (such as strcpy and wcscpy) and look for a null character to terminate the string instead of requiring an explicit size argument to be passed. (Some of these functions accept a specified maximum length, but they also check for premature termination with a null character.) The array arguments and return values for these functions have type char * and wchar_t * respectively, and the array elements are referred to as "characters" and "wide characters".

In many cases, there are both mem and str/wcs versions of a function. The one that is more appropriate to use depends on the exact situation. When your program is manipulating arbitrary arrays or blocks of storage, then you should always use the mem functions. On the other hand, when you are manipulating null-terminated strings it is usually more convenient to use the str/wcs functions, unless you already know the length of the string in advance. The wmem functions should be used for wide character arrays with known size.

Some of the memory and string functions take single characters as arguments. Since a value of type char is automatically promoted into an value of type int when used as a parameter, the functions are declared with int as the type of the parameter in question. In case of the wide character function the situation is similarly: the parameter type for a single wide character is wint_t and not wchar_t. This would for many implementations not be necessary since the wchar_t is large enough to not be automatically promoted, but since the ISO C standard does not require such a choice of types the wint_t type is used.