C in a Nutshell

Name

strxfrm

Synopsis

Transforms a string for easier locale-specific comparison

#include <string.h>
size_tstrxfrm( 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] ...