_stricmp, _wcsicmp, _mbsicmp, _stricmp_l, _wcsicmp_l, _mbsicmp_l

Article
01/11/2013

Perform a lowercase comparison of strings.

Important

_mbsicmp and _mbsicmp_l cannot be used in applications that execute in the Windows Runtime. For more information, see CRT functions not supported with /ZW.

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.

Return Value

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.

Remarks

The _stricmp function lexicographically compares lowercase versions of string1 and string2 and returns a value indicating their relationship. _stricmp differs from _stricoll in that the _stricmp comparison is affected by LC_CTYPE, whereas the _stricoll comparison is according to the LC_CTYPE and LC_COLLATE categories of the locale. For more information on 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. For more information, see Locale.

Note

_stricmp is equivalent to _strcmpi. They can be used interchangeably but _stricmp is the preferred standard.

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

Requirements

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 in the Introduction.

Example

// 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

.NET Framework Equivalent

System::String::Compare

Share via