1 out of 8 rated this helpful - Rate this topic

_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l

Visual Studio 2005

Compare 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.

Return Value

Indicates the relationship between the substrings as follows.

Return value	Description
< 0	string1 substring less than string2 substring
0	string1 substring identical to string2 substring
> 0	string1 substring 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 '`') will 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 without the _l suffix use the current locale for their locale-dependent behavior. 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, 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	Compatibility
_strnicmp, _strnicmp_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
_wcsnicmp, _wcsnicmp_l	<string.h> or <wchar.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
_mbsnicmp, _mbsnicmp_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.

Example

See the example for strncmp.

.NET Framework Equivalent

System::String::Compare

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

Did you find this helpful? Yes No

Not accurate

Not enough depth

Need more code examples

(1500 characters remaining)

Community Additions

ADD