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

_mbsnbcoll, _mbsnbicoll

Compare n bytes of two multibyte character strings using multibyte code page information.

int _mbsnbcoll(
   const unsigned char *string1,
   const unsigned char string2,
   size_t count 
);
int _mbsnbicoll(
   const unsigned char *string1,
   const unsigned char string2,
   size_t count 
);

Parameters

string1, string2
Strings to compare.
count
Number of bytes to compare.

Return Value

The return value indicates the relation of the substrings of string1 and string2.

Return value Description
< 0 string1 substring less than string2 substring
0 string1 substring identical to string2 substring
> 0 string1 substring greater than string2 substring

Each of these functions returns _NLSCMPERROR on an error. To use _NLSCMPERROR, include either STRING.H or MBSTRING.H.

Remarks

Each of these functions collates, at most, the first count bytes in string1 and string2 and returns a value indicating the relationship between the resulting substrings of string1 and string2. If the final byte in the substring of string1 or string2 is a lead byte, it is not included in the comparison; these functions compare only complete characters in the substrings. _mbsnbicoll is a case-insensitive version of _mbsnbcoll. Like _mbsnbcmp and _mbsnbicmp, _mbsnbcoll and _mbsnbicoll collate the two multibyte-character strings according to the lexicographic order specified by the multibyte code page currently in use.

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 of strings by bytes in such an instance, use _mbsnbcoll rather than _mbsnbcmp; to check only for string equality, use _mbsnbcmp.

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 comparison.

Generic-Text Routine Mappings

TCHAR.H routine _UNICODE & _MBCS not defined _MBCS defined _UNICODE defined
_tcsncoll _strncoll _mbsnbcoll _wcsncoll
_tcsnicoll _strnicoll _mbsnbicoll _wcsnicoll

Requirements

Routine Required header Compatibility
_mbsnbcoll <mbstring.h> Win 98, Win Me, Win NT, Win 2000, Win XP
_mbsnbicoll <mbstring.h> 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

String Manipulation Routines | _mbsnbcat | _mbsnbcmp | _mbsnbicmp | strcoll Functions | strncmp | _strnicmp | 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.