strxfrm

strxfrm

Transform a String Using Locale-Dependent Information

Portability: ISO/ANSI C conforming

SYNOPSIS
DESCRIPTION
RETURN VALUE
CAUTION
IMPLEMENTATION
EXAMPLE

SYNOPSIS

#include <string.h>

size_t strxfrm(char *str1, const char *str2, size_t n);

DESCRIPTION

strxfrm transforms the string pointed to by str2 using the collating sequence or routines (or both) defined by the LC_COLLATE category of the current locale. The resulting string is placed into the array pointed to by str1 .

The transformation is such that if the strcmp function is applied to two transformed strings, it returns greater than, equal to, or less than 0 , corresponding to the result of the strcoll function applied directly to the two original strings.

No more than n characters are placed into the resulting array pointed to by str1 , including the terminating null character. If n is 0 , str1 is permitted to be NULL . The results are unpredictable if the strings pointed to by str1 and str2 overlap.

RETURN VALUE

strxfrm returns the length of the transformed string (not including the terminating null character). If the value returned is n or more, the first n characters are written to the array without null termination. In the " S370 " locale, the behavior of strxfrm is like that of strncpy except that the number of characters copied to the output array is returned instead of a pointer to the copied string.

CAUTION

If the str2 argument is not properly terminated or n is bigger than the output array pointed to by str1 , then a protection or addressing exception may occur. The size of the output array needed to hold the transformed string pointed to by str2 can be determined by the following statement:

size_needed = 1 + strxfrm(NULL, str1, 0);

IMPLEMENTATION

strxfrm uses the following logic when transforming a string:

strxfrm calls the locale's strxfrm function equivalent, if available, to transform str2 and place the result in the str1 array. See LOCALE strxfrm EQUIVALENT.
strxfrm calls the library's double-byte strxfrm collation routine with a standard double-byte collating sequence if the locale is a double-byte locale as determined from the LC_COLLATE category, no locale strxfrm function is available, and no collation table is supplied.
strxfrm uses a collation table to transform the string if the locale is a single-byte locale and has a collation table available.
strxfrm invokes the equivalent of strncpy to copy str2 to str1 if none of the above are true.

EXAMPLE

This example verifies that strcmp yields the same result as strcoll when it is used to compare two strings transformed by strxfrm .

#include <locale.h>
#include <string.h>

main()
{
   char *str1, *str2,                       /* input strings pointers */
   txf1[80],  txf2[80];                     /* transform arrays       */
   int result_strcoll, result_strcmp;       /* compare results        */

   str1 = " A B C D";
   str2 = " A C B";

   if ((strxfrm(txf1, str1, sizeof(txf1)) < sizeof(txf1)) &&
       (strxfrm(txf2, str2, sizeof(txf2)) < sizeof(txf2)))
      result_strcmp = strcmp(txf1, txf2);
   else exit(4);                   /* error exit if length is too big */

   result_strcoll = strcoll(str1, str2);    /* Get strcoll result.    */

      /* Result must be 0 or result signs must be the same.           */
   if ((result_strcmp == result_strcoll) ||
       (result_strcmp*result_strcoll > 0))
      exit(0);
   else exit(8);                            /* Else this is an error. */
}

Chapter Contents
Previous
Next
Top of Page