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

strcoll Functions

Each of the strcoll and wcscoll functions compares two strings according to the LC_COLLATE category setting of the locale code page currently in use. Each of the _mbscoll functions compares two strings according to the multibyte code page currently in use. Use the coll functions for string comparisons when there is a difference between the character set order and the lexicographic character order in the current code page and this difference is of interest for the comparison. Use the corresponding cmp functions to test only for string equality.

strcoll Functions

SBCS Unicode MBCS Description
strcoll wcscoll _mbscoll Collate two strings
_stricoll _wcsicoll _mbsicoll Collate two strings (case insensitive)
_strncoll _wcsncoll _mbsncoll Collate first count characters of two strings
_strnicoll _wcsnicoll _mbsnicoll Collate first count characters of two strings (case-insensitive)

Remarks

The single-byte character (SBCS) versions of these functions (strcoll, stricoll, _strncoll, and _strnicoll) compare string1 and string2 according to the LC_COLLATE category setting of the current locale. These functions differ from the corresponding strcmp functions in that the strcoll functions use locale code page information that provides collating sequences. For string comparisons in locales in which the character set order and the lexicographic character order differ, the strcoll functions should be used rather than the corresponding strcmp functions. For more information on LC_COLLATE, see setlocale.

For some code pages and corresponding character sets, the order of characters in the character set may differ from the lexicographic character order. In the "C" locale, this is not the case: the order of characters in the ASCII character set is the same as the lexicographic order of the characters. However, in certain European code pages, for example, the character 'a' (value 0x61) precedes the character 'ä' (value 0xE4) in the character set, but the character 'ä' precedes the character 'a' lexicographically. To perform a lexicographic comparison in such an instance, use strcoll rather than strcmp. Alternatively, you can use strxfrm on the original strings, then use strcmp on the resulting strings.

strcoll, stricoll, _strncoll, and _strnicoll automatically handle multibyte-character strings according to the locale code page currently in use, as do their wide-character (Unicode) counterparts. The multibyte-character (MBCS) versions of these functions, however, collate strings on a character basis according to the multibyte code page currently in use.

Because the coll functions collate strings lexicographically for comparison, whereas the cmp functions simply test for string equality, the coll functions are much slower than the corresponding cmp versions. Therefore, the coll functions should be used only when there is a difference between the character set order and the lexicographic character order in the current code page and this difference is of interest for the string comparison.

See Also

Locale Routines | String Manipulation Routines | localeconv | _mbsnbcoll | setlocale | strcmp | strncmp | _strnicmp | strxfrm | 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.