wcstring(3C)

DESCRIPTION

The arguments ws1, ws2, and ws point to wide character strings (arrays of type wchar_t terminated by a null value).

wcscat() appends a copy of wide string ws2 to the end of wide string ws1. wcsncat() appends a maximum of n characters; fewer if ws2 is shorter than n characters. Each returns a pointer to the null-terminated result (the value of ws1).

wcscmp() compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether ws1 is lexicographically less than, equal to, or greater than ws2. The comparison of corresponding wide characters is done by comparing numeric values of the wide character codes. Null pointer values for ws1 and ws2 are treated the same as pointers to empty wide strings. wcsncmp() makes the same comparison but examines a maximum of n characters (n less than or equal to zero yields equality).

wcscpy() copies wide string ws2 to ws1, stopping after the null value has been copied. wcsncpy() copies up to n characters from ws2, adding null values to ws1 if necessary, until a total of n have been 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 character.

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 _XOPEN_SOURCE=500 environment. The third argument ptr points to a caller-provided wchar_t pointer into which wcstok() stores information necessary 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, or 0 if wc 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 character 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 behavior 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>.

APPLICATION USAGE

The "Unix Standards Only" prototypes are available to applications if they are:

To get the MSE behavior of the "Unix Standards Only" prototype of wcstok(), the application MUST be compiled with the environment variable UNIX_STD set to the value 98 or above and exported.

EXTERNAL INFLUENCES

ERRORS

wcswidth() fails if the following condition is encountered:

wcsxfrm() fails under the following conditions:

EXAMPLES

The following sample piece of code finds the tokens, separated by blanks, that are in the string s (assuming that there are at most MAXTOK tokens):

WARNINGS

The functions wcscat(), wcsncat(), wcscpy(), wcsncpy(), wcstok(), wcsstr(), and wcstok_r() alter the contents of the array to which ws1 points. They do not check for overflow of the array.

Null pointers for destination wide strings cause undefined behavior.

Wide character movement is performed differently in different implementations, so copying that involves overlapping source and destination wide strings may yield unexpected results.

For the wcscoll() function, the results are undefined if the languages specified by the LC_COLLATE and LC_CTYPE categories use different code sets.

wcstok_r() is an obsolescent interface supported only for compatibility with existing DCE applications. New multithreaded applications should use wcstok().

wcswidth() will return an incorrect negative value if the number of column positions required for n wide characters in the wide string pointed to by ws exceeds INT_MAX.

AUTHOR

wcstring functions were developed by OSF and HP.

SEE ALSO

memory(3C), multibyte(3C), setlocale(3C), string(3C), wconv(3C), thread_safety(5), glossary(9).

STANDARDS CONFORMANCE

wcscat(): XPG4

wcschr(): XPG4

wcscmp(): XPG4

wcscoll(): XPG4

wcscpy(): XPG4

wcscspn(): XPG4

wcslen(): XPG4

wcsncat(): XPG4

wcsncmp(): XPG4

wcsncpy(): XPG4

wcspbrk(): XPG4

wcsrchr(): XPG4

wcsspn(): XPG4

wcstok(): XPG4

wcswcs(): XPG4

wcswidth(): XPG4

wcwidth(): XPG4

wcsxfrm(): XPG4