Export (0) Print
Expand All
Expand Minimize
1 out of 2 rated this helpful - Rate this topic

_stricmp, _wcsicmp, _mbsicmp

Perform a lowercase 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 
);

Parameters

string1, string2
Null-terminated strings to compare.

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 current locale. For more information on the LC_COLLATE category, see setlocale and Locale Categories.

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:

#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
}

Generic-Text Routine Mappings

TCHAR.H routine _UNICODE & _MBCS not defined _MBCS defined _UNICODE defined
_tcsicmp _stricmp _mbsicmp _wcsicmp

Requirements

Routine Required header Compatibility
_stricmp <string.h> Win 98, Win Me, Win NT, Win 2000, Win XP
_wcsicmp <string.h> or <wchar.h> Win 98, Win Me, Win NT, Win 2000, Win XP
_mbsicmp <mbstring.h> Win 98, Win Me, Win NT, Win 2000, Win XP

For additional compatibility information, see Compatibility in the Introduction.

Libraries

All versions of the C run-time libraries.

Example

// crt_strcmp.c

#include <string.h>
#include <stdio.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( tmp, "greater than" );
   else if( result < 0 )
      strcpy( tmp, "less than" );
   else
      strcpy( 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( tmp, "greater than" );
   else if( result < 0 )
      strcpy( tmp, "less than" );
   else
      strcpy( tmp, "equal to" );
   printf( "   _stricmp:  String 1 is %s string 2\n", tmp );
}

Output

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

See Also

String Manipulation Routines | memcmp | _memicmp | strcmp | strcoll Functions | strncmp | _strnicmp | strrchr | _strset | strspn | Run-Time Routines and .NET Framework Equivalents

Show:
© 2014 Microsoft. All rights reserved.