### strxfrm -- Transform String

Format

>     #include <string.h>
>     size_t strxfrm(char *str1, const char *str2, size_t n);

Language Level: ANSI, XPG4
strxfrm transforms the string pointed to by str2 and places the resulting string into the array pointed to by str1. The transformation is determined by the program's locale. The transformed string may not be displayable or printable, but can be used with the strcmp or strncmp functions.

The result of applying strcoll to two separate strings before their transformation is equal to the result of applying strcmp, or strncmp, to the same two strings after their transformation.

No more than n bytes are placed into the area pointed to by str1, including the terminating null byte. If n is 0, str1 can be a NULL pointer.

Return Value
strxfrm returns the length of the transformed string (excluding the null byte). When n is 0 and str1 is a null pointer, the length returned is one less than the number of bytes required to contain the transformed string. If an error occurs, strxfrm function returns (size_t)-1 and sets errno to indicate the error.

Notes:

1. The string returned by strxfrm contains the weights for each order of the characters within the string. As a result, the string returned may be longer than the input string; it does not contain printable characters.
2. strxfrm calls malloc when the LC_COLLATE category specifies backward on the order_start keyword, the substitute keyword is specified, or the locale has one-to-many mapping. If malloc fails, strxfrm also fails.
3. If the locale supports double-byte characters (MB_CUR_MAX specified as 2), strxfrm validates the multibyte characters. (Previously it did not validate the string.) strxfrm will fail if the string contains invalid multibyte characters.
4. If MB_CUR_MAX is defined as 2, and no collation is defined for DBCS chars in the current locale, the DBCS characters will collate after the single-byte characters.

Example

localeconv -- Retrieve Numeric Formatting Convention
setlocale -- Set Locale
strcmp -- Compare Strings
strcoll -- Compare Strings
strncmp -- Compare Strings
wcsxfrm -- Transform Wide-Character String
<string.h>