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

w
wcstring(3C) wcstring(3C)
copied. The result is not null-terminated if the length of ws2 is n or more. Each function returns ws1.
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 position 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 com-
parison 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 charac-
ter 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 over-
lap, 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 1: September 2005 − 2 − Hewlett-Packard Company Section 3−−1047