This documentation is archived and is not being maintained.

_strnicoll, _wcsnicoll, _mbsnicoll

Compare strings using locale-specific information.

int _strnicoll(
   const char *string1,
   const char *string2,
   size_t count 
int _wcsnicoll(
   const wchar_t *string1,
   const wchar_t *string2 ,
   size_t count 
int _mbsnicoll(
   const unsigned char *string1,
   const unsigned char *string2,
   size_t count 


string1, string2
Null-terminated strings to compare
Number of characters to compare

Return Value

Each of these functions returns a value indicating the relationship of the substrings of string1 and string2, as follows.

Return value Relationship of string1 to string2
< 0 string1 less than string2
0 string1 identical to string2
> 0 string1 greater than string2

Each of these functions returns _NLSCMPERROR. To use _NLSCMPERROR, include either STRING.H or MBSTRING.H. _wcsnicoll can fail if either string1 or string2 contains wide-character codes outside the domain of the collating sequence. When an error occurs, _wcsnicoll may set errno to EINVAL. To check for an error on a call to _wcsnicoll, set errno to 0 and then check errno after calling _wcsnicoll.


Each of these functions performs a case-insensitive comparison of the first count characters in string1 and string2 according to the code page currently in use. These 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.

Generic-Text Routine Mappings

TCHAR.H routine _UNICODE & _MBCS not defined _MBCS defined _UNICODE defined
_tcsncicoll _strnicoll _mbsnbicoll _wcsnicoll
_tcsnicoll _strnicoll _mbsnbicoll _wcsnicoll


Routine Required header Compatibility
_strnicoll <string.h> Win 98, Win Me, Win NT, Win 2000, Win XP
_wcsnicoll <wchar.h> or <string.h> Win 98, Win Me, Win NT, Win 2000, Win XP
_mbsnicoll <mbstring.h> Win 98, Win Me, Win NT, Win 2000, Win XP

For additional compatibility information, see Compatibility in the Introduction.


All versions of the C run-time libraries.

See Also

Locale Routines | String Manipulation Routines | strcoll Functions Overview | localeconv | _mbsnbcoll | setlocale | strcmp | _stricmp | strncmp | _strnicmp | strxfrm | Run-Time Routines and .NET Framework Equivalents