String/Array Conventions (The GNU C Library)

### 5.2 String and Array Conventions ¶

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

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 strings have names beginning with ‘`str`’ and ‘`wcs`’ respectively (such as `strcpy` and `wcscpy`) and look for a terminating null byte or null wide character 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.) The array arguments and return values for these functions have type `char *` and `wchar_t *` respectively, and the array elements are referred to as “bytes” 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 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 a 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 functions the situation is similar: the parameter type for a single wide character is `wint_t` and not `wchar_t`. This would for many implementations not be necessary since `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.