| Standards / Extensions | C or C++ | Dependencies |
|---|---|---|
ISO C Amendment |
both |
#include <wchar.h>
size_t wcsxfrm(wchar_t * __restrict__wcs1,
const wchar_t * __restrict__wcs2, size_t n);Transforms the wide-character string pointed to by wcs2 to values which represent character collating weights and places the resulting wide-character string into the array pointed to by wcs1. The transformation is such that if the wcscmp() function is applied to two transformed wide-character strings, it returns a value greater than, equal to, or less than zero, corresponding to the result of the wcscoll() function applied to the same two original wide-character strings. No more than n elements are placed into the resulting array pointed to by wcs1, including the terminating NULL wide-character code. If n is zero, wcs1 is permitted to be a NULL pointer. If copying takes place between objects that overlap, the behavior is undefined.
Since no return value is reserved to indicate an error, an application wishing to check for error situations should set errno to 0, then call wcsxfrm(), then check errno.
Returns the length of the 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 wcs1 are indeterminate.
If wcs1 is a NULL pointer, wcsxfrm() returns the number of elements required to contain the transformed wide string.
The transformed value of invalid wide-character codes shall be either less than or greater than the transformed values of valid wide-character codes depending on the option chosen for the particular locale definition. In this case wcsxfrm() returns (size_t)-1.
wcsxfrm() is controlled by the LC_COLLATE category.
The EILSEQ error may be set, indicating that the wide character string pointed to by wcs2 contains wide character codes outside the domain of the collating sequence.
⁄* CELEBW28 *⁄
#include <stdio.h>
#include <wchar.h>
int main(void)
{
wchar_t *wcs;
wchar_t buffer[80];
int length;
printf("Type in a string of characters.\n");
wcs = fgetws(buffer, 80, stdin);
length = wcsxfrm(NULL, wcs, 0);
printf("You would need a %d element array to hold the wide string", length);
printf("\n\n%ls\n\ntransformed according", wcs);
printf(" to this program's locale.\n");
}