strxfrm - Transform String

Syntax

#include <string.h>
size_t strxfrm(char *str1, const char *str2, size_t n);

strxfrm transforms the string pointed to by str2 and places the resulting string into the array pointed to by str1. The transformation is determined by the program's locale. The transformed string is not necessarily readable, but can be used with the strcmp or strncmp functions. qsort and bsearch can also be used on the results.

The transformation is such that, if strcmp or strncmp were applied to the two transformed strings, the results would be the same as applying strcoll to the two corresponding untransformed strings.

No more than n bytes are placed into the area pointed to by str1, including the terminating null byte. If n is 0, str1 can be a null pointer.

strxfrm returns the length of the transformed string (excluding the null byte). When n is 0 and str1 is a null pointer, the length returned is one less than the number of bytes required to contain the transformed string. If an error occurs, strxfrm function returns (size_t)-1 and sets errno to indicate the error.

Note:

The string returned by strxfrm may be longer than the input string; it does not contain printable characters.
strxfrm calls malloc when the LC_COLLATE category specifies backward on the order_start keyword, the substitute keyword is specified, or the locale has one-to-many mapping. If malloc fails, strxfrm also fails.

This example uses strxfrm to transform two different strings that have the same collating weight. It then calls strcmp to compare the new strings.

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

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

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

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

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

[Back]

[Next]