wcsxfrm - transform wide character string

Syntax	#include <wchar.h> size_t wcsxfrm(wchar_t *ws1, const wchar_t *ws2, size_t n);
Description	wcsxfrm() transforms the wide character string pointed to by ws2, and writes the result of the transformation to the field pointed to by ws1. The transformation is performed such that the wcscmp() function returns the same return value (greater than, equal to or less than zero) for two transformed wide character strings as the wcscoll() function does for the two original non-transformed wide character strings. A maximum of n wide character codes are written to the field (including the terminating null character). If n is 0, wc1 can be a null pointer. If copying is between overlapping objects, the result is undefined.
Return val.	Integer value < n
		indicating the number of wide character codes written to the field (without terminating null).
	Integer value >= n
		in this case the content of the ws1 field is undefined.
	(size_t) - 1	if an error occurs. errno is set to indicate the error.
Errors	wcsxfrm() will fail if:
	EINVAL	The wide character string pointed to by ws2 contains wide character codes from outside the value range of the selected collation sequence.
	ENOMEM	There is not enough memory available for the internal management data.
Notes	Transformation is such that two transformed wide character strings are arranged by wcscmp() in accordance with the collation sequence defined in LC_COLLATE. The fact that ws1 can be a null pointer if n is 0, is useful if the size of the field is to be determined before the transformation. Because there is no default value defined for if an error occurs, it is advisable to set errno to 0, then call wcscoll() and after the call check errno. If errno is not 0, assume that an error has occurred. Restriction This version of the C runtime system only supports 1-byte characters as wide character codes. They are of type wchar_t (see stddef.h). (End)
See also	wcscmp(), wcscoll(), wchar.h.