_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l

Compares 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 with /ZW.

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 an error, _mbsnicmp returns _NLSCMPERROR, which is defined in STRING.H and MBSTRING.H.

Remarks

The _strnicmp function lexicographically compares, at most, the first count characters of string1 and string2. The comparison is performed without regard to case; _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 and return value of _wcsnicmp are wide-character strings; those 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.

Generic-Text Routine Mappings

TCHAR.H routine

_UNICODE & _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 additional compatibility information, see Compatibility.

Example

See the example for strncmp.

.NET Framework Equivalent

System::String::Compare

See Also

Reference

String Manipulation (CRT)

strcat, wcscat, _mbscat

strcmp, wcscmp, _mbscmp

strcpy, wcscpy, _mbscpy

strncat, _strncat_l, wcsncat, wcsncat_l, _mbsncat _mbsncat_l

strncmp, wcsncmp, _mbsncmp, _mbsncmp_l

strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l

strrchr, wcsrchr, _mbsrchr, _mbsrchr_l

_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l

strspn, wcsspn, _mbsspn, _mbsspn_l