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.

Locale Routines |  String Manipulation Routines

See Also   localeconv, _mbsnbcoll, setlocale, strcmp, strncmp, _strnicmp, strxfrm