NAME

wsxfrm − wide character string transformation

SYNOPSIS

#include <widec.h>

size_t wsxfrm(wchar_t ∗dst, const wchar_t ∗src, size_t n);

MT-LEVEL

Safe with exceptions

DESCRIPTION

wsxfrm() transforms the string src and places the resulting string into the array dst. If wscmp() is applied to two transformed strings, it will return the same result as wscoll() applied to the same two original strings.  The transformation is based on the program’s locale for category LC_COLLATE (see setlocale(3C)). 

No more than n wide characters will be placed into the resulting array pointed to by dst, including the terminating null character.  If n is 0 and dst is NULL, wsxfrm() returns the number of bytes required to transform the string, but performs no copying.  If you only want the size of a transformed string, this is faster since no copying takes place.  If copying takes place between objects that overlap, the behavior is undefined. 

wsxfrm() returns the length of the transformed string (not including the terminating null character), unless it fails.  If the value returned is n or more, the contents of the array dst are indeterminate. 

RETURN VALUES

On failure, wsxfrm() returns (size_t)−1. 

EXAMPLES

The value of the following expression is the size of the array needed to hold the transformation of the string pointed to by s. 

1 + wsxfrm(NULL, s, 0);

FILES

/usr/lib/locale/locale/LC_COLLATE
LC_COLLATE database for locale

SEE ALSO

colltbl(1M), setlocale(3C), wscoll(3I), wstring(3I), environ(5)

NOTES

wsxfrm() can be used safely in a multi-thread application, as long as setlocale(3C) is not being called to change the locale. 

Sun Microsystems  —  Last change: 22 Jan 1993