wcsxfrm - Transform Wide-Character String

Syntax

#include <wchar.h>
size_t wcsxfrm(wchar_t *wcs1, const wchar_t *wcs2, size_t n);

wcsxfrm transforms the wide-character string pointed to by wcs2 to values that represent character collating weights and places the resulting wide-character string into the array pointed to by wcs1. The transformation is determined by the program's locale. The transformed string is not necessarily readable, but can be used with the wcscmp function.

The transformation is such that if wcscmp were applied to two transformed wide-character strings, the results would be the same as applying the wcscoll function to the two corresponding untransformed strings.

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

The behavior of wcsxfrm is controlled by the LC_COLLATE category of the current locale.

wcsxfrm returns the length of the transformed wide-character string (excluding the terminating null wide character). 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.

If wcs2 contains invalid wide characters, wcsxfrm returns (size_t)-1. The transformed values of the invalid characters are either less than or greater than the transformed values of valid wide characters, depending on the option chosen for the particular locale definition.

If wcs2 contains wide characters outside the domain of the collating sequence. wcsxfrm sets errno to EILSEQ.

This example uses wcsxfrm to transform two different strings with the same collating weight. It then uses wcscmp to compare the new strings.

#include <stdlib.h>
#include <stdio.h>
#include <locale.h>
#include <wchar.h>

int main(void)
{
   wchar_t *string1 = L"stride ng1";
   wchar_t *string2 = L"stri*ng1";
   wchar_t *newstring1, *newstring2;
   int  length1, length2;

   if (NULL == setlocale(LC_ALL, "Fr_FR")) {
      printf("setlocale failed.\n");
      exit(EXIT_FAILURE);
   }
   length1 = wcsxfrm(NULL, string1, 0);
   length2 = wcsxfrm(NULL, string2, 0);
   if (NULL == (newstring1 = calloc(length1 + 1, sizeof(wchar_t))) ||
       NULL == (newstring2 = calloc(length2 + 1, sizeof(wchar_t)))) {
      printf("insufficient memory\n");
      exit(EXIT_FAILURE);
   }
   if ((wcsxfrm(newstring1, string1, length1 + 1) != length1) ||
       (wcsxfrm(newstring2, string2, length2 + 1) != length2)) {
      printf("error in string processing\n");
      exit(EXIT_FAILURE);
   }
   if (0 != wcscmp(newstring1, newstring2))
      printf("wrong results\n");
   else
      printf("correct results\n");
   return 0;

   /****************************************************************************
      The output should be similar to :

      correct results
   ****************************************************************************/
}

[Back]

[Next]