strxfrm

Changes a string such that the changed string can be passed to the strcmp function and produce the same result as passing the unchanged string to the strcoll function.

Format

#include  <string.h>

size_t strxfrm  (char *s1, const char *s2, size_t
                maxchar);

Arguments

s1, s2

Pointers to character strings.

maxchar

The maximum number of bytes (including the null terminator) to be stored in s1.

Description

If the value of maxchar is less than the required size to store the transformed string (including the terminating null), the contents of the array pointed to by s1 is indeterminate. In such a case, the function returns the size of the transformed string.

If maxchar is 0, then s1 is allowed to be a NULL pointer, and the function returns the required size of the s1 array before making the transformation.

The string comparison functions, strcoll and strcmp, can produce different results given the same two string to compare. The reason for this is that strcmp does a straightforward comparison of the code point values of the characters in the strings, whereas strcoll uses the locale information to do the comparison. Depending on the locale, the strcoll comparison can be a multipass operation, which is slower than strcmp.

The purpose of the strxfrm function is to transform strings in such a way that if you pass two transformed strings to the strcmp function, the result is the same as passing the two original strings to the strcoll function. The strxfrm function is useful in applications that need to do a large number of comparisons on the same strings using strcoll. In this case, it might be more efficient (depending on the locale) to transform the strings once using strxfrm, and then do comparisons using strcmp.

Return Value .

x	Length of the resulting string pointed to by s1, not including the terminating null character. No return value is reserved for error indication. However, the function can set errno to EINVAL - The string pointed to by ws2 contains characters outside the domain of the collating sequence

Example

/* This test verifies that two transformed strings when passed   */
/* through strxfrm and then compared, provide the same result as */
/* if passed through strcoll without any transformation.         */

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

#define  BUFF_SIZE  256

main()
{

char string1[BUFF_SIZE];
char string2[BUFF_SIZE];
int  errno;
int  coll_result;
int  strcmp_result;
size_t  strxfrm_result1;
size_t  strxfrm_result2;

/* setlocale to French locale */

if(setlocale(LC_ALL,"fr_FR.ISO8859-1") == NULL)
 {
  perror("setlocale");
  exit(EXIT_FAILURE);
 }

/* collate string 1 and string 2 and store the result */

errno = 0;
coll_result = strcoll("àbcd", "abcz");
if (errno)
    {
    perror("strcoll");
    exit(EXIT_FAILURE);
    }

else
    {
    /* Transform the strings (using strxfrm) into string1 and string2 */

    strxfrm_result1 = strxfrm(string1,"àbcd",BUFF_SIZE);

    if (strxfrm_result1 == ((size_t)-1))
 {
        perror("strxfrm");
        exit(EXIT_FAILURE);
        }

    else if (strxfrm_result1 > BUFF_SIZE)
        {
        perror("\n** String is too long **\n");
        exit(EXIT_FAILURE);
        }

    else
        {
        strxfrm_result2 = strxfrm(string2,"abcz",BUFF_SIZE);
        if (strxfrm_result2 == ((size_t)-1))
           {
           perror("strxfrm");
           exit(EXIT_FAILURE);
           }

 else if (strxfrm_result2 > BUFF_SIZE)
           {
           perror("\n** String is too long **\n");
           exit(EXIT_FAILURE);
           }

        /* Compare the two transformed strings and verify that the result */
        /* is the same as the result from strcoll on the original strings */
        else
           {
            strcmp_result = strcmp(string1,string2);
            if (strcmp_result == 0 && (coll_result == 0))
              {
              printf("\nReturn value from strcoll() and return value \
                                        from strcmp() are both zero.");
              printf("\nTest successful\n\n");
              }

            else if ((strcmp_result < 0) && (coll_result < 0))
              {
              printf("\nReturn value from strcoll() and return value \
                                        from strcmp() are less than zero.");
              printf("\nTest successful\n\n");
              }

            else if ((strcmp_result > 0) && (coll_result > 0))
              {
              printf("\nReturn value from strcoll() and return value \
                                      from strcmp() are greater than zero.");
              printf("\nTest successful\n\n");
              }

            else
              {
              printf("** Error **\n");
              printf("\nReturn values are not of the same type");
              }
            }
        }
    }
}

Running the example program produces the following result:

Return value from strcoll() and return value
               from strcmp() are less than zero.
Test successful