NAME
wcsxfrm, wcsxfrm_l
— transform a wide string under
locale
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include
<wchar.h>
size_t
wcsxfrm(wchar_t *restrict ws1,
const wchar_t *restrict ws2, size_t
n);
#include <wchar.h>
#include <xlocale.h>
size_t
wcsxfrm_l(wchar_t *restrict ws1,
const wchar_t *restrict ws2, size_t
n, locale_t loc);
DESCRIPTION
The
wcsxfrm()
function transforms a null-terminated wide character string pointed to by
ws2, according to the current locale's collation
order, then copies the transformed string into ws1. No
more than n wide characters are copied into
ws1, including the terminating null character. If
n is set to 0 (it helps to determine an actual size
needed for transformation), ws1 is permitted to be a
NULL pointer.
Comparing two strings using
wcscmp()
after wcsxfrm() is equivalent to comparing two
original strings with
wcscoll().
Although the
wcsxfrm()
function uses the current locale, the
wcsxfrm_l()
function may be passed a locale directly. See
xlocale(3) for more information.
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 ws1 are indeterminate.
SEE ALSO
STANDARDS
The wcsxfrm() function conforms to
ISO/IEC 9899:1999
(“ISO C99”).
BUGS
The current implementation of wcsxfrm()
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 ws1, whereas
wcscoll() compares characters using both primary and
secondary weights.