GNU Info

Info Node: (libc.info)String/Array Conventions

(libc.info)String/Array Conventions


Next: String Length Prev: Representation of Strings Up: String and Array Utilities
Enter node , (file) or (file)node

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.


automatically generated by info2www version 1.2.2.9