wcsxfrm()

transform wide character string 

Function

SYNOPSIS

#include <wchar.h>

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

DESCRIPTION

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);

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.

RETURN VALUES

The wcsxfrm() function returns 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() encounters a character outside of the collating sequence defined for the current locale, it sets errno to EINVAL.

CONFORMANCE

ANSI/ISO 9899-1990/AM 1-1995.

MULTITHREAD SAFETY LEVEL

MT-Safe, with exceptions.

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

PORTING ISSUES

None.

AVAILABILITY

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

SEE ALSO

Functions:
localeconv(), setlocale(), wcscmp(), wcscoll(), wcsncmp()

MKS Toolkit 9.2 Documentation Build 16.