wcsxfrm(3C)

wcsxfrm -- wide character string transformation

Synopsis

#include <wchar.h.h>

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

Description

wcsxfrm is part of the X/Open Portability Guide Issue 4 optional Enhanced Internationalization feature group.

wcsxfrm transforms the wide character string pointed to by ws2 and places the resulting wide character string into the array pointed to by ws1. The transformation does the following:

If wcscmp is applied to two transformed wide strings, it returns a value greater than, or equal to, zero, corresponding to the result of wcscoll applied to the same two original wide character strings.

No more than n wide-character codes are placed into the resulting array pointed to by wcs1, including the terminating null wide-character code. If n is zero, wcs1 can be a null pointer. If copying takes place between objects that overlap, the behavior is undefined.

Return values

wcsxfrm returns the length necessary to hold the entire transformed wide character string, not including the terminating null wide-character code. If the value returned is n or more, the contents of the array pointed to by ws1 are indeterminate. wcsxfrm returns -1 and sets errno to ENOSYS.

Errors

wcsxfrm may fail if

EINVAL: The ws1 or ws2 arguments contain wide character codes outside the domain of the collating sequence.
ENOSYS: The function is not supported

Usage

Since no return value is reserved to show an error, if you want to check for errors, you should set errno to 0, call wcscoll, and then check errno. If it is non-zero, you can assume that an error has occurred.

References

strxfrm(3C), wchar(5), wcscoll(3C)