_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_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 _strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l.
Compares the specified number of characters of two strings without regard to case.
|
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.
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>.
The _strnicmp function ordinally 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; 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 |
| 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.
See the example for strncmp.
String Manipulation
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