WCSXFRM(3)

NAME
wcsxfrm, wcsxfrm_l - transform a wide string under locale

LIBRARY
libc

SYNOPSIS
#include <wchar.h>
size_t
wcsxfrm(wchar_t * restrict dst, const wchar_t * restrict src, size_t n);
size_t
wcsxfrm_l(wchar_t * restrict dst, const wchar_t * restrict src, size_t n, locale_t locale);

DESCRIPTION
The wcsxfrm() function transforms a null-terminated wide character string pointed to by src according to the current locale collation order then copies the transformed string into dst. No more than n wide characters are copied into dst, including the terminating null character added. If n is set to 0 (it helps to determine an actual size needed for transformation), dst is permitted to be a NULL pointer.

Comparing two strings using wcscmp() after wcsxfrm() is equivalent to comparing two original strings with wcscoll().

The wcsxfrm_l() function is identical to wcsxfrm() but takes an explicit locale argument, whereas wcsxfrm() uses the current global or per-thread locale.

RETURN VALUES
Upon successful completion, wcsxfrm() and wcsxfrm_l() return the length of the transformed string not including the terminating null character. If this value is n or more, the contents of dst are indeterminate.

SEE ALSO
setlocale(3), strxfrm(3), wcscmp(3), wcscoll(3)

STANDARDS
The wcsxfrm() function conforms to isoC-99. The wcsxfrm_l() function conforms to p1003.1-2008.

BUGS
The current implementation of wcsxfrm() and wcsxfrm_l() only works in single-byte LC_CTYPE locales, and falls back to using wcsncpy() in locales with extended character sets.

Comparing two strings using wcscmp() after wcsxfrm() is not always equivalent to comparison with wcscoll(); wcsxfrm() only stores information about primary collation weights into dst, whereas wcscoll() compares characters using both primary and secondary weights.