NAME

wcscat(), wcsncat(), wcscmp(), wcsncmp(), wcscpy(), wcsncpy(), wcslen(), wcschr(), wcsrchr(), wcspbrk(), wcsspn(), wcscspn(), wcswcs(), wcstok(), wcstok_r(), wcscoll(), wcwidth(), wcswidth() − wide character string operations

SYNOPSIS

#include <wchar.h>

wchar_t *wcscat(wchar_t *ws1, const wchar_t *ws2);

wchar_t *wcsncat(wchar_t *ws1, const wchar_t *ws2, size_t n);

int wcscmp(const wchar_t *ws1, const wchar_t *ws2);

int wcsncmp(const wchar_t *ws1, const wchar_t *ws2, size_t n);

wchar_t *wcscpy(wchar_t *ws1, const wchar_t *ws2);

wchar_t *wcsncpy(wchar_t *ws1, const wchar_t *ws2, size_t n);

size_t wcslen(const wchar_t *ws);

wchar_t *wcschr(const wchar_t *ws, wint_t wc);

wchar_t *wcsrchr(const wchar_t *ws, wint_t wc);

wchar_t *wcspbrk(const wchar_t *ws1, const wchar_t *ws2);

size_t wcsspn(const wchar_t *ws1, const wchar_t *ws2);

size_t wcscspn(const wchar_t *ws1, const wchar_t *ws2);

wchar_t *wcswcs(const wchar_t *ws1, const wchar_t *ws2);

wchar_t *wcstok(wchar_t *ws1, const wchar_t *ws2);

wchar_t *wcstok_r(wchar_t *ws1, const wchar_t *ws2, wchar_t **wlast);

int wcscoll(const wchar_t *ws1, const wchar_t *ws2);

int wcwidth(wint_t wc);

int wcswidth(const wchar_t *ws, size_t n);

Remarks:

These functions are compliant with the XPG4 Worldwide Portability Interface wide-character string handling functions.  They parallel the 8 bit string functions defined in string(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. 

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.

wcstok_r() is identical to wcstok(), except that it expects to be passed the address of a wide-character string pointer as the third argument.  It will use this argument to keep track of the current position in the string being searched.  It returns a pointer to the current token in the string or a NULL value if there are no more tokens. 

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, or -1 if ws contains an unprintable wide character. 

Definitions for these functions and the type wchar_t are provided in header file <wchar.h>. 

EXTERNAL INFLUENCES

Locale

The LC_COLLATE category determines the collation ordering used by the wcscoll() function.  See nlsinfo(1) to determine the collation used for a particular locale.

The LC_CTYPE category determines how widths are calculated by the wcwidth() and wcswidth() functions. 

EXAMPLE

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):

int i = 0;
wchar_t *ws, *wlast, *wtok[MAXTOK];
 wtok[0] = wcstok_r(ws, L" ", &wlast);
while (wtok[++i] = wcstok_r(NULL, L" ", &wlast));

WARNINGS

The functions wcscat(), wcsncat(), wcscpy(), wcsncpy(), wcstok(), 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() is unsafe in multi-thread applications.  wcstok_r() is safe for multi-thread applications and should be used instead. 

AUTHOR

wcstring functions were developed by OSF and HP. 

SEE ALSO

nlsinfo(1), wconv(3C), memory(3C), multibyte(3C), setlocale(3C), string(3C), hpnls(5). 

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

Hewlett-Packard Company  —  HP-UX Release 10.20:  July 1996