Export (0) Print
Expand All
div
eof
Expand Minimize

_strncoll, _wcsncoll, _mbsncoll, _strncoll_l, _wcsncoll_l, _mbsncoll_l 

Compare strings using locale-specific information.


int _strncoll(
   const char *string1,
   const char *string2,
   size_t count 
);
int _wcsncoll(
   const wchar_t *string1,
   const wchar_t *string2,
   size_t count 
);
int _mbsncoll(
   const unsigned char *string1,
   const unsigned char *string2,
   size_t count 
);
int _strncoll_l(
   const char *string1,
   const char *string2,
   size_t count,
   _locale_t locale
);
int _wcsncoll_l(
   const wchar_t *string1,
   const wchar_t *string2,
   size_t count,
   _locale_t locale
);
int _mbsncoll_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 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. _wcsncoll can fail if either string1 or string2 contains wide-character codes outside the domain of the collating sequence. When an error occurs, _wcsncoll may set errno to EINVAL. To check for an error on a call to _wcsncoll, set errno to 0 and then check errno after calling _wcsncoll.

Each of these functions performs a case-sensitive 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 code page and this difference is of interest for the string comparison. The character set order is locale-dependent. The versions of these functions without the _l suffix use the current locale; the versions with the _l suffix are identical except that they use the locale passed in instead.

All of these functions validate their parameters. If either string1 or string2 is a null pointer, or 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

_tcsnccoll

_strncoll

_mbsncoll

_wcsncoll

_tcsncoll

_strncoll

_mbsnbcoll

_wcsncoll

Routine Required header Compatibility

_strncoll, _strncoll_l

<string.h>

Windows 95, Windows 98, Windows 98 Second Edition, Windows Millennium Edition, Windows NT 4.0, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003

_wcsncoll, _wcsncoll_l

<wchar.h> or <string.h>

Windows 95, Windows 98, Windows 98 Second Edition, Windows Millennium Edition, Windows NT 4.0, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003

_mbsncoll, _mbsncoll_l

<mbstring.h>

Windows 95, Windows 98, Windows 98 Second Edition, Windows Millennium Edition, Windows NT 4.0, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003

For additional compatibility information, see Compatibility in the Introduction.

Community Additions

ADD
Show:
© 2014 Microsoft