Export (0) Print
Expand All
Expand Minimize
This topic has not yet been rated - Rate this topic

strxfrm, wcsxfrm

Transform a string based on locale-specific information.

size_t strxfrm(
   char *strDest,
   const char *strSource,
   size_t count 
);
size_t wcsxfrm(
   wchar_t *strDest,
   const wchar_t *strSource,
   size_t count 
);

Parameters

strDest
Destination string.
strSource
Source string.
count
Maximum number of characters to place in strDest.

Return Value

Returns the length of the transformed string, not counting the terminating null character. If the return value is greater than or equal to count, the content of strDest is unpredictable. On an error, each function sets errno and returns INT_MAX.

Remarks

The strxfrm function transforms the string pointed to by strSource into a new collated form that is stored in strDest. No more than count characters, including the null character, are transformed and placed into the resulting string. The transformation is made using the current locale's LC_COLLATE category setting. For more information on LC_COLLATE, see setlocale.

After the transformation, a call to strcmp with the two transformed strings yields results identical to those of a call to strcoll applied to the original two strings. As with strcoll and stricoll, strxfrm automatically handles multibyte-character strings as appropriate.

wcsxfrm is a wide-character version of strxfrm; the string arguments of wcsxfrm are wide-character pointers. For wcsxfrm, after the string transformation, a call to wcscmp with the two transformed strings yields results identical to those of a call to wcscoll applied to the original two strings. wcsxfrm and strxfrm behave identically otherwise.

Generic-Text Routine Mappings

TCHAR.H routine _UNICODE & _MBCS not defined _MBCS defined _UNICODE defined
_tcsxfrm strxfrm strxfrm wcsxfrm

In the "C" locale, the order of the characters in the character set (ASCII character set) is the same as the lexicographic order of the characters. However, in other locales, the order of characters in the character set may differ from the lexicographic character order. For example, in certain European locales, the character 'a' (value 0x61) precedes the character 'ä' (value 0xE4) in the character set, but the character 'ä' precedes the character 'a' lexicographically.

In locales for which the character set and the lexicographic character order differ, use strxfrm on the original strings and then strcmp on the resulting strings to produce a lexicographic string comparison according to the current locale's LC_COLLATE category setting. Thus, to compare two strings lexicographically in the above locale, use strxfrm on the original strings, then strcmp on the resulting strings. Alternatively, you can use strcoll rather than strcmp on the original strings.

The value of the following expression is the size of the array needed to hold the strxfrm transformation of the source string:

1 + strxfrm( NULL, string, 0 )

In the "C" locale only, strxfrm is equivalent to the following:

strncpy( _string1, _string2, _count );
return( strlen( _string1 ) );

Requirements

Routine Required header Compatibility
strxfrm <string.h> ANSI, Win 98, Win Me, Win NT, Win 2000, Win XP
wcsxfrm <string.h> or <wchar.h> ANSI, Win 98, Win Me, Win NT, Win 2000, Win XP

For additional compatibility information, see Compatibility in the Introduction.

Libraries

All versions of the C run-time libraries.

See Also

Data Conversion Routines, Locale Routines, String Manipulation | strcoll Functions | localeconv | setlocale | strcmp | strncmp | Run-Time Routines and .NET Framework Equivalents

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.