`_strncoll`, `_wcsncoll`, `_mbsncoll`, `_strncoll_l`, `_wcsncoll_l`, `_mbsncoll_l`

Article
2023-01-31

Compares strings by using locale-specific information.

Important

_mbsncoll and _mbsncoll_l cannot be used in applications that execute in the Windows Runtime. For more information, see CRT functions not supported in Universal Windows Platform apps.

Syntax

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
The number of characters to compare.

locale
The locale to use.

Return value

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

Return value	Relationship of `string1` to `string2`
< 0	`string1` is less than `string2`.
0	`string1` is identical to `string2`.
> 0	`string1` is 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 that are 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 the _wcsncoll call.

Remarks

Each of these functions performs a case-sensitive comparison of the first count characters in string1 and string2, according to the code page that's currently in use. Use these functions only when there's a difference between the character set order and the lexicographic character order in the code page, and when this difference matters for the string comparison. The character set order is locale-dependent. The versions of these functions that don't have the _l suffix use the current locale, but the versions that have the _l suffix use the locale that's passed in. For more information, see Locale.

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.

By default, this function's global state is scoped to the application. To change this behavior, see Global state in the CRT.

Generic-text routine mappings

TCHAR.H routine	`_UNICODE` and `_MBCS` not defined	`_MBCS` defined	`_UNICODE` defined
`_tcsnccoll`	`_strncoll`	`_mbsncoll`	`_wcsncoll`
`_tcsncoll`	`_strncoll`	`_mbsnbcoll`	`_wcsncoll`

Requirements

Routine	Required header
`_strncoll`, `_strncoll_l`	<string.h>
`_wcsncoll`, `_wcsncoll_l`	<wchar.h> or <string.h>
`_mbsncoll`, `_mbsncoll_l`	<mbstring.h>

For more compatibility information, see Compatibility.

Share via

_strncoll, _wcsncoll, _mbsncoll, _strncoll_l, _wcsncoll_l, _mbsncoll_l