Header File 

string.h  

Category 

Memory and String Manipulation Routines 

Prototype 

size_t strxfrm(char *target, const char *source, size_t n); 

size_t wcsxfrm(wchar_t *target, const wchar_t *source, size_t n); 

Description 

Transforms a portion of a string to a specified collation. 

strxfrm transforms the string pointed to by source into the string target for no more than n characters. The transformation is such that if the strcmp function is applied to the resulting strings, its return corresponds with the return values of the strcoll function. 

No more than n characters, including the terminating null character, are copied to target. 

strxfrm transforms a character string into a special string according to the current locale's LC_COLLATE category. The special string that is built can be compared with another of the same type, byte for byte, to achieve a locale-correct collation result. These special strings, which can be thought of as keys or tokenized strings, are not compatible across the different locales. 

The tokens in the tokenized strings are built from the collation weights used by strcoll from the active locale's collation tables. 

Processing stops only after all levels have been processed for the character string or the length of the tokenized string is equal to the maxlen parameter. 

All redundant tokens are removed from each level's set of tokens. 

The tokenized string buffer must be large enough to contain the resulting tokenized string. The length of this buffer depends on the size of the character string, the number of collation levels, the rules for each level and whether there are any special characters in the character string. Certain special characters can cause extra character processing of the string resulting in more space requirements. For example, the French character "oe" will take double the space for itself because in some locales, it expands to collation weights for each level. Substrings that have substitutions will also cause extra space requirements. 

There is no safe formula to determine the required string buffer size, but at least (levels * string length) are required. 

Return Value 

Number of characters copied not including the terminating null character. If the value returned is greater than or equal to n, the content of target is indeterminate. 

Example  

#include <stdio.h>
#include <string.h>
#include <alloc.h>
int main(void)
{
   char *target;
   char *source = "Frank Borland";
   int length;
   /* allocate space for the target string */
   target = (char *) calloc(80, sizeof(char));
   /* copy the source over to the target and get the length */
   length = strxfrm(target, source, 80);
   /* print out the results */
   printf("%s has the length %d\n", target, length);
   return 0;
}

Portability