WCSXFRM(3)

NAME
wcsxfrm, and 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 loc);

DESCRIPTION
The wcsxfrm() function transform 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 function wcsxfrm_l() does the same but uses the locale provided as parameter, see xlocale(3).

RETURN VALUES
Upon successful completion, wcsxfrm() returns 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), xlocale(3)

STANDARDS
WCSXFRM(3)

The wcsxfrm() function conforms to isoC-99.

NAME
wcsxfrm, wcsxfrm_l - transform a wide string under locale

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

DESCRIPTION
The idea of wcsxfrm() and wcsxfrm_l() is to “un-localize” a wide string: the functions transform src, storing the result in dst, such that wcscmp(3) on transformed wide strings returns what wcscoll(3) on the original untransformed wide strings would return.

On OpenBSD, both have the same effect as wcslcpy(3), and the global locale, the thread-specific locale, and the locale argument are ignored. On other operating systems, the behaviour may depend on the LC_CTYPE and LC_COLLATE locale categories set with setlocale(3), uselocale(3), or newlocale(3).

SEE ALSO
newlocale(3), setlocale(3), wcscmp(3), wcscoll(3), wcslcpy(3)

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

HISTORY
The wcsxfrm() function has been available since OpenBSD 4.8, and wcsxfrm_l() since OpenBSD 6.2.