HP-UX Reference (11i v2 04/09) - 3 Library Functions N-Z (vol 7)

w
wcstring(3C) wcstring(3C)
Note that wcsncpy() should not be used to copy an arbitrary structure. If that structure contains
sizeof(wchar_t) consecutive null bytes,
wcsncpy() may not copy the entire structure. Use the
memcpy() function (see memory(3C)) to copy arbitrary binary data.
wcslen() returns the number of wide characters in ws, not including the terminating null wide charac-
ter.
wcschr() (wcsrchr()) returns a pointer to the first (last) occurrence of wide character wc in wide
string ws, or a null pointer if wc does not occur in the wide string. The null wide character terminating a
wide string is considered to be part of the wide string.
wcsstr() locates the first occurrence in the wide-character string pointed to by ws1 of the sequence of
wide-characters (excluding the terminating null wide-character) in the wide-character string pointed to
by ws2. On successful completion,
wcsstr() returns a pointer to the located wide-character string, or a
null pointer if the wide-character string is not found. If ws2 points to a wide-character string with zero
length, the function returns ws1.
wcspbrk() returns a pointer to the first occurrence in wide string ws1 of any wide character from wide
string ws2, or a null pointer if no wide character from ws2 exists in ws1.
wcsspn() (wcscspn()) returns the length of the maximum initial segment of wide string ws1, which
consists entirely of wide characters from (not from) wide string ws2.
wcswcs() returns a pointer to the first occurrence of wide string ws2 in wide string ws1, or a null
pointer if ws2 does not occur in the wide string. If ws2 points to a wide string of zero length,
wcswcs()
returns ws1.
wcstok() considers the wide string ws1 to consist of a sequence of zero or more text tokens separated
by spans of one or more wide characters from the separator wide string ws2. The first call (with a non-
null pointer ws1 specified) returns a pointer to the first wide character of the first token, and writes a null
wide character into ws1 immediately following the returned token. The function keeps track of its posi-
tion in the wide string ws1 between separate calls, so that subsequent calls made with the first argument
a null pointer work through the wide string immediately following that token. In this way subsequent
calls work through the wide string ws1 until no tokens remain. The separator wide string ws2 can be
different from call to call. When no token remains in ws1, a null pointer is returned.
The third argument is added for the
_INCLUDE__STDC_A1_SOURCE
environment. The third argu-
ment ptr points to a caller-provided
wchar_t pointer into which wcstok() stores information neces-
sary for it to continue scanning the same wide-character string.
wcscoll() returns an integer greater than, equal to, or less than zero, according to whether the wide
string pointed to by ws1 is greater than, equal to, or less than the wide string pointed to by ws2. The
comparison is based on wide strings interpreted as appropriate to the program’s locale (see Locale below).
In the ‘‘C’’ locale
wcscoll() works like wcscmp().
wcwidth() returns the number of column positions required for the wide character wc,or0ifwc is a
null wide character, or -1 if wc is an unprintable wide character.
wcswidth() returns the number of column positions required for n wide characters (or fewer than n
wide characters if a null wide character is encountered before n wide characters are exhausted) in the
wide string pointed to by ws. wcswidth() returns 0 if ws points to a null wide character.
wcswidth() returns -1 if ws contains an unprintable wide character, or if ws is a NULL pointer; in
either case errno [EINVAL] is set.
wcsxfrm() transforms the wide character string pointed to by ws2 and places the resulting wide char-
acter string into the array pointed to by ws1. The transformation is such that if wcscmp() is applied to
two transformed wide strings, it returns a value greater than, equal to or less than 0, corresponding to
the result of wcscoll() applied to the same two original wide character strings. No more than n wide-
character codes are placed into the resulting array pointed to by ws1 including the terminating null
wide-character. If n is 0, ws1 is permitted to be a null pointer. If copying takes place between objects that
overlap, the behaviour is undefined. wcsxfrm() returns the length of the transformed wide character
string (not including the terminating null wide-character code). If the value returned is n or more, the
contents of the array pointed to by ws1 are indeterminate. On error, wcsxfrm() returns (size_t) -1, and
sets errno to [EINVAL] (if the wide character string pointed to by ws2 contains wide-character codes
outside the domain of the collating sequence) or to [ENOSYS] (if the function is not supported).
Definitions for these functions and the type
wchar_t are provided in header file <wchar.h>.
HP-UX 11i Version 2: September 2004 − 2 − Hewlett-Packard Company Section 3−−1165