wcsxfrm(), wcsxfrm_l() -- transform wide character string

SYNOPSIS

#include <wchar.h>

size_t wcsxfrm(wchar_t *ws1, const wchar_t *ws2, size_t n);

#include <locale.h>

size_t wcsxfrm_l(wchar_t *ws1, const wchar_t *ws2, size_t n, locale_t locale);

The wcsxfrm() function transforms the string pointed to by ws2 so that wcscmp() can be used for lexical comparisons, taking into consideration the value of LC_COLLATE. The transformations performed by wcsxfrm() are such that, if two strings are transformed, the lexical relationship of the transformed strings as determined by wcscmp() is the same as the lexical relationship of the original strings as determined by wcscoll(). The transformed string is placed into the buffer pointed to by ws1.

If n is zero, then ws1 may be NULL. In this case, wcsxfrm() returns the number of characters in ws2 it would transform. The terminating NULL character is not included.

For the C locale, wcsxfrm() is equivalent to:

wcsncpy(ws1, ws2, n);
return wcslen(ws1);

wcsxfrm_l() behaves in the same way as wcsxfrm() without the _l suffix, but uses the specified locale rather than the global or per-thread locale. A locale_t is returned by newlocale().

PARAMETERS

ws1: Is either NULL, or a pointer to a buffer to hold the transformed string.
ws2: Is the string to be transformed.
n: Is the maximum number of characters to transform.

locale

Is a locale_t perhaps returned by newlocale() or LC_GLOBAL_LOCALE or 0 for the current thread locale set with uselocale().

RETURN VALUES

The wcsxfrm() and wcsxfrm_l() functions return the length of the transformed string, excluding the terminating null character. If the value returned is n or more, the contents of the array pointed to by ws1 are undetermined.

If wcsxfrm() or wcsxfrm_l() encounters a character outside of the collating sequence defined for the current locale, it sets errno to EINVAL.

CONFORMANCE

wcsxfrm() conforms to ANSI/ISO 9899:1990 'ISO C90'

wcsxfrm_l() conforms to IEEE Std 1003.1-2008 'POSIX.1'

MULTITHREAD SAFETY LEVEL

MT-Safe, with exceptions.

The function wcsxfrm() is MT-Safe as long as no thread calls setlocale() while this function is executing.

The function wcsxfrm_l() is MT-Safe as long as no thread calls freelocale() on locale while this function is executing.

PORTING ISSUES

None.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

wcsxfrm(), wcsxfrm_l()
transform wide character string

Function