`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`

Artikkeli
2022-12-02

Compares the specified number of characters of two strings without regard to case.

Important

_mbsnicmp and _mbsnicmp_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 _strnicmp(
   const char *string1,
   const char *string2,
   size_t count
);
int _wcsnicmp(
   const wchar_t *string1,
   const wchar_t *string2,
   size_t count
);
int _mbsnicmp(
   const unsigned char *string1,
   const unsigned char *string2,
   size_t count
);
int _strnicmp_l(
   const char *string1,
   const char *string2,
   size_t count,
   _locale_t locale
);
int _wcsnicmp_l(
   const wchar_t *string1,
   const wchar_t *string2,
   size_t count,
   _locale_t locale
);
int _mbsnicmp_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
Locale to use.

Return value

Indicates the relationship between the substrings, as follows.

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

On a parameter validation error, these functions return _NLSCMPERROR, which is defined in <string.h> and <mbstring.h>.

Remarks

The _strnicmp function compares, at most, the first count characters of string1 and string2. The comparison is performed without regard to case by converting each character to lowercase. _strnicmp is a case-insensitive version of strncmp. The comparison ends if a terminating null character is reached in either string before count characters are compared. If the strings are equal when a terminating null character is reached in either string before count characters are compared, the shorter string is lesser.

The characters from 91 to 96 in the ASCII table ('[', '\', ']', '^', '_', and '`') evaluate as less than any alphabetic character. This ordering is identical to that of stricmp.

_wcsnicmp and _mbsnicmp are wide-character and multibyte-character versions of _strnicmp. The arguments of _wcsnicmp are wide-character strings. The arguments of _mbsnicmp are multibyte-character strings. _mbsnicmp recognizes multibyte-character sequences according to the current multibyte code page and returns _NLSCMPERROR on an error. For more information, see Code pages. These three functions behave identically otherwise. These functions are affected by the locale setting—the versions that don't have the _l suffix use the current locale for their locale-dependent behavior; the versions that do have the _l suffix instead 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, 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
`_tcsncicmp`	`_strnicmp`	`_mbsnicmp`	`_wcsnicmp`
`_tcsnicmp`	`_strnicmp`	`_mbsnbicmp`	`_wcsnicmp`
`_tcsncicmp_l`	`_strnicmp_l`	`_mbsnicmp_l`	`_wcsnicmp_l`

Requirements

Routine	Required header
`_strnicmp`, `_strnicmp_l`	<string.h>
`_wcsnicmp`, `_wcsnicmp_l`	<string.h> or <wchar.h>
`_mbsnicmp`, `_mbsnicmp_l`	<mbstring.h>

For more compatibility information, see Compatibility.

Example

See the example for strncmp.

Jaa

_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l