strxfrm

strxfrm

Transforms a string for easier locale-specific comparison

#include <string.h>
size_t strxfrm ( char * restrict dest , const char * restrict src , size_t n  );

The strxfrm( ) function transforms the string addressed by src, and copies the result to the char array addressed by dest. The third argument, n, specifies a maximum number of characters (including the terminating null character) that the function may write to dest. The locations that strxfrm( ) reads from and writes to using its restricted pointer parameters must not overlap.

The transformation performed depends on the value of the locale category LC_COLLATE, which you can query or set using the setlocale( ) function. Furthermore, the strxfrm( ) transformation is related to the strcoll( ) function in the following way: If you use strcmp( ) to compare two strings produced by strxfrm( ) calls, the result is the same as if you use strcoll( ) to compare the original strings passed to strxfrm( ). Using strxfrm( ) and strcmp( ) may be more efficient than strcoll( ) if you need to use the same string in many comparisons.

The strxfrm( ) function returns the length of the transformed version of the string, not counting the terminating null character. If this length is greater than or equal to n, then the contents of the array at dest are indeterminate. The value of n may also be 0, in which case dest may be a null pointer.

Example

typedef struct stringpair { char * original;
                            char * xformed; } Stringpair_t ;

Stringpair_t stringpairs[8] =
             { { "Chávez", NULL },        { "Carron", NULL    },
               { "Canoso", NULL },        { "Cañoso", NULL    },
               { "Carteño", NULL },       { "Cortillo", NULL  },
               { "Cortiluz S.A.", NULL }, { "Corriando", NULL } };

char xformbuffer[1024];         // Space to catch each strxfrm( ) result.

int stringpaircmp( const void * p1, const void *p2 );
                                // Defined externally.

setlocale( LC_COLLATE, "" );    // Use the host system's locale setting.

for ( int i = 0; i < 8 ; i++ )
{
  stringpairs[i].xformed
                  = malloc( strxfrm( xformbuffer, originals[i], 1024 ) +1 );
  if ( stringpairs[i].xformed != NULL )
    strcpy( stringpairs[i]->xformed, xformbuffer );
};

qsort( stringpairs, 8, sizeof(Stringpair_t), stringpaircmp );

The qsort( ) function invoked in the last line of this example would pass the transformed strings to a comparison function named stringpaircmp( ). That function would compare the transformed strings using strcmp( ), rather than comparing the originals using strcoll( ).

Example

See Also