_stricmp, _wcsicmp, _mbsicmp, _stricmp_l, _wcsicmp_l, _mbsicmp_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 _stricmp, _wcsicmp, _mbsicmp, _stricmp_l, _wcsicmp_l, _mbsicmp_l.
Performs a case-insensitive comparison of strings.
|
int _stricmp( const char *string1, const char *string2 ); int _wcsicmp( const wchar_t *string1, const wchar_t *string2 ); int _mbsicmp( const unsigned char *string1, const unsigned char *string2 ); int _stricmp_l( const char *string1, const char *string2, _locale_t locale ); int _wcsicmp_l( const wchar_t *string1, const wchar_t *string2, _locale_t locale ); int _mbsicmp_l( const unsigned char *string1, const unsigned char *string2, _locale_t locale );
Parameters
string1, string2
Null-terminated strings to compare.
locale
Locale to use.
The return value indicates the relation of string1 to string2 as follows.
| Return value | Description |
|---|---|
| < 0 | string1 less than string2 |
| 0 | string1 identical to string2 |
| > 0 | string1 greater than string2 |
On an error, _mbsicmp returns _NLSCMPERROR, which is defined in <string.h> and <mbstring.h>.
The _stricmp function ordinally compares string1 and string2 after converting each character to lowercase, and returns a value indicating their relationship. _stricmp differs from _stricoll in that the _stricmp comparison is only affected by LC_CTYPE, which determines which characters are upper and lowercase. The _stricoll function compares strings according to both the LC_CTYPE and LC_COLLATE categories of the locale, which includes both the case and the collation order. For more information about the LC_COLLATE category, see setlocale and Locale Categories. The versions of these functions without the _l suffix use the current locale for locale-dependent behavior. The versions with the suffix are identical except that they use the locale passed in instead. If the locale has not been set, the C locale is used. For more information, see Locale.
|
The _strcmpi function is equivalent to _stricmp and is provided for backward compatibility only.
Because _stricmp does lowercase comparisons, it may result in unexpected behavior.
To illustrate when case conversion by _stricmp affects the outcome of a comparison, assume that you have the two strings JOHNSTON and JOHN_HENRY. The string JOHN_HENRY will be considered less than JOHNSTON because the "_" has a lower ASCII value than a lowercase S. In fact, any character that has an ASCII value between 91 and 96 will be considered less than any letter.
If the strcmp function is used instead of _stricmp, JOHN_HENRY will be greater than JOHNSTON.
_wcsicmp and _mbsicmp are wide-character and multibyte-character versions of _stricmp. The arguments and return value of _wcsicmp are wide-character strings; those of _mbsicmp are multibyte-character strings. _mbsicmp 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.
_wcsicmp and wcscmp behave identically except that wcscmp does not convert its arguments to lowercase before comparing them. _mbsicmp and _mbscmp behave identically except that _mbscmp does not convert its arguments to lowercase before comparing them.
You will need to call setlocale for _wcsicmp to work with Latin 1 characters. The C locale is in effect by default, so, for example, ä will not compare equal to Ä. Call setlocale with any locale other than the C locale before the call to _wcsicmp. The following sample demonstrates how _wcsicmp is sensitive to the locale:
// crt_stricmp_locale.c
#include <string.h>
#include <stdio.h>
#include <locale.h>
int main() {
setlocale(LC_ALL,"C"); // in effect by default
printf("\n%d",_wcsicmp(L"ä", L"Ä")); // compare fails
setlocale(LC_ALL,"");
printf("\n%d",_wcsicmp(L"ä", L"Ä")); // compare succeeds
}
An alternative is to call _create_locale, _wcreate_locale and pass the returned locale object as a parameter to _wcsicmp_l.
All of these functions validate their parameters. If either string1 or string2 are null pointers, 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 |
|---|---|---|---|
_tcsicmp | _stricmp | _mbsicmp | _wcsicmp |
| Routine | Required header |
|---|---|
_stricmp, _stricmp_l | <string.h> |
_wcsicmp, _wcsicmp_l | <string.h> or <wchar.h> |
_mbsicmp, _mbsicmp_l | <mbstring.h> |
For additional compatibility information, see Compatibility.
// crt_stricmp.c
#include <string.h>
#include <stdio.h>
#include <stdlib.h>
char string1[] = "The quick brown dog jumps over the lazy fox";
char string2[] = "The QUICK brown dog jumps over the lazy fox";
int main( void )
{
char tmp[20];
int result;
// Case sensitive
printf( "Compare strings:\n %s\n %s\n\n", string1, string2 );
result = strcmp( string1, string2 );
if( result > 0 )
strcpy_s( tmp, _countof(tmp), "greater than" );
else if( result < 0 )
strcpy_s( tmp, _countof(tmp), "less than" );
else
strcpy_s( tmp, _countof(tmp), "equal to" );
printf( " strcmp: String 1 is %s string 2\n", tmp );
// Case insensitive (could use equivalent _stricmp)
result = _stricmp( string1, string2 );
if( result > 0 )
strcpy_s( tmp, _countof(tmp), "greater than" );
else if( result < 0 )
strcpy_s( tmp, _countof(tmp), "less than" );
else
strcpy_s( tmp, _countof(tmp), "equal to" );
printf( " _stricmp: String 1 is %s string 2\n", tmp );
}
Compare strings: The quick brown dog jumps over the lazy fox The QUICK brown dog jumps over the lazy fox strcmp: String 1 is greater than string 2 _stricmp: String 1 is equal to string 2
String Manipulation
memcmp, wmemcmp
_memicmp, _memicmp_l
strcmp, wcscmp, _mbscmp
strcoll Functions
strncmp, wcsncmp, _mbsncmp, _mbsncmp_l
_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l
strrchr, wcsrchr, _mbsrchr, _mbsrchr_l
_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l
strspn, wcsspn, _mbsspn, _mbsspn_l