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

Return Value

The return value indicates the relation of string1 to string2 as follows.

On an error, _mbsicmp returns _NLSCMPERROR, which is defined in <string.h> and <mbstring.h>.

Remarks

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

Requirements

For additional compatibility information, see Compatibility.

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

See Also

Reference

String Manipulation (CRT)

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