C in a Nutshell

Name

wcsxfrm

Synopsis

Transforms a wide string for easier locale-specific comparison

#include <wchar.h>
size_twcsxfrm( wchar_t * restrict dest, const wchar_t * restrict src,
                size_t n );

The wcsxfrm() function transforms the wide string addressed by src, and copies the result to the wchar_t array addressed by dest. The third argument, n, specifies a maximum number of wide characters (including the terminating null wide character) that the function may write to dest. The locations that wcsxfrm() reads from and writes to using its restricted pointer parameters must not overlap.

The transformation performed depends on the value of the locale category LC_COLLATE, which you can query or set using the setlocale() function. Furthermore, the wcsxfrm() transformation is related to the wcscoll() function in the following way: if you use wcscmp() to compare two strings produced by wcsxfrm() calls, the result is the same as if you use wcscoll() to compare the original strings passed to wcsxfrm(). Using wcsxfrm() and wcscmp() may be more efficient than wcscoll() if you need to use the same string in many comparisons.

The wcsxfrm() function returns the length of the transformed version of the string, not counting the terminating null character. If this length is greater than or equal to n, then the contents of the array at dest are indeterminate. The value of n may also be 0, in which case dest may be a null pointer.

Example

typedef struct stringpair { wchar_t * original; wchar_t * xformed; } Stringpair_t ...