### wcsxfrm -- Transform Wide-Character String

Format

>     #include <wchar.h>
>     size_t wcsxfrm(wchar_t *wcs1, const wchar_t *wcs2, size_t n);

Language Level: ANSI 93, XPG4
wcsxfrm transforms the wide-character string pointed to by wcs2 to values that represent character collating weights and places the resulting wide-character string into the array pointed to by wcs1. The transformation is determined by the program's locale. The transformed string may not be displayable or printable but, can be used with the wcscmp function.

The transformation is such that if wcscmp were applied to two transformed wide-character strings, the results would be the same as applying the wcscoll function to the two corresponding untransformed strings.

No more than n elements are placed into the resulting array pointed to by wcs1, including the terminating null wide character. If n is 0, wcs1 can be a null pointer. If copying takes place between objects that overlap, the behavior is undefined.

The behavior of wcsxfrm is controlled by the LC_COLLATE category of the current locale.

Return Value
wcsxfrm returns the length of the transformed wide-character string (excluding the terminating null wide character). If the value returned is n or more, the contents of the array pointed to by wcs1 are indeterminate.

If wcs1 is a null pointer, wcsxfrm returns the number of elements required to contain the transformed wide string.

If wcs2 contains invalid wide characters, wcsxfrm returns (size_t)-1. The transformed values of the invalid characters are either less than or greater than the transformed values of valid wide characters, depending on the option chosen for the particular locale definition.

If wcs2 contains wide characters outside the domain of the collating sequence. wcsxfrm sets errno to EILSEQ.

Example

strxfrm -- Transform String
wcscmp -- Compare Wide-Character Strings
wcscoll -- Compare Wide-Character Strings
<wchar.h>