wcsxfrm(S)

wcsxfrm -- transform wide character string

Syntax

cc . . . -lc

#include <wchar.h>

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

Description

wcsxfrm(S) transforms a wide character string, such that the relative order (i.e., sign) of two transformed strings as determined by wcscmp(S) is the same as that determined by wcscoll(S) when applied to the same two original strings. The input string is ws2 and the output string is placed in the array pointed to by ws1. The transformed string, including the null terminator, cannot have more than n wide-character codes. Otherwise, the contents in the array ws1 are undefined.

If n is zero, ws1 can be a null pointer. The value returned by wcscoll(S) may be used to determine the minimum required size for the ws1 array.

If the memory areas pointed to by ws1 and ws2 overlap within n wide-character codes, the behavior is undefined.

Return values

wcsxfrm( ) returns the number of wide characters of the transformed string. The null terminator is not counted. If this number is n or more, the contents in the array ws1 are undefined.

If there is an error, (size_t)-1 is returned and errno is set.

Diagnostics

wcsxfrm( ) may fail if one or more of the following is true:

[EINVAL]: At least one wide-character code in the string ws2 is not in the domain of the collating sequence.
[ENOSYS]: The routine is not supported.

Standards conformance