We recommend using Visual Studio 2017

_strnicoll, _wcsnicoll, _mbsnicoll, _strnicoll_l, _wcsnicoll_l, _mbsnicoll_l

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at _strnicoll, _wcsnicoll, _mbsnicoll, _strnicoll_l, _wcsnicoll_l, _mbsnicoll_l.

Compares strings by using locale-specific information.

System_CAPS_ICON_important.jpg Important

_mbsnicoll and _mbsnicoll_l cannot be used in applications that execute in the Windows Runtime. For more information, see CRT functions not supported with /ZW.

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   
);  
int _strnicoll_l(  
   const char *string1,  
   const char *string2,  
   size_t count,  
   _locale_t locale  
);  
int _wcsnicoll_l(  
   const wchar_t *string1,  
   const wchar_t *string2 ,  
   size_t count,  
   _locale_t locale  
);  
int _mbsnicoll_l(  
   const unsigned char *string1,  
   const unsigned char *string2,  
   size_t count,  
   _locale_t locale  
);  

Parameters

string1, string2
Null-terminated strings to compare

count
Number of characters to compare

locale
The locale to use.

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

Return valueRelationship of string1 to string2
< 0string1 less than string2
0string1 identical to string2
> 0string1 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. These functions should be used only when there is a difference between the character set order and the lexicographic character order in the code page and this difference is of interest for the string comparison. The versions of these functions without the _l suffix use the current locale and code page. The versions with the_l suffix are identical except that they use the locale passed in instead. For more information, see Locale.

All of these functions validate their parameters. If either string1 or string2 is a null pointer, or if count is greater than INT_MAX, the invalid parameter handler is invoked, as described in Parameter Validation . If execution is allowed to continue, these functions return _NLSCMPERROR and set errno to EINVAL.

Generic-Text Routine Mappings

TCHAR.H routine_UNICODE & _MBCS not defined_MBCS defined_UNICODE defined
_tcsncicoll_strnicoll_mbsnbicoll_wcsnicoll
_tcsnicoll_strnicoll_mbsnbicoll_wcsnicoll
_tcsnicoll_l_strnicoll_l_mbsnbicoll_l_wcsnicoll_l
RoutineRequired header
_strnicoll, _strnicoll_l<string.h>
_wcsnicoll, _wcsnicoll_l<wchar.h> or <string.h>
_mbsnicoll, _mbsnicoll_l<mbstring.h>

For additional compatibility information, see Compatibility.

System::String::Compare

Locale
String Manipulation
strcoll Functions
localeconv
_mbsnbcoll, _mbsnbcoll_l, _mbsnbicoll, _mbsnbicoll_l
setlocale, _wsetlocale
strcmp, wcscmp, _mbscmp
_stricmp, _wcsicmp, _mbsicmp, _stricmp_l, _wcsicmp_l, _mbsicmp_l
strncmp, wcsncmp, _mbsncmp, _mbsncmp_l
_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l
strxfrm, wcsxfrm, _strxfrm_l, _wcsxfrm_l

Show: