strncmp, wcsncmp, _mbsncmp, _mbsncmp_l

Compare characters of two strings, using the current locale or a specified locale.

int strncmp(
   const char *string1,
   const char *string2,
   size_t count 
);
int wcsncmp(
   const wchar_t *string1,
   const wchar_t *string2,
   size_t count 
);
int _mbsncmp(
   const unsigned char *string1,
   const unsigned char *string2,
   size_t count 
);
int _mbsncmp_l(
   const unsigned char *string1,
   const unsigned char *string2,
   size_t count, 
   _locale_t locale
);

Parameters

  • string1, string2
    Strings to compare.

  • count
    Number of characters to compare.

  • locale
    Locale to use.

Return Value

The return value indicates the relation of the substrings of string1 and string2 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, _mbsncmp returns _NLSCMPERROR, which is defined in STRING.H and MBSTRING.H.

Remarks

The strncmp function lexicographically compares, at most, the first count characters in string1 and string2 and returns a value indicating the relationship between the substrings. strncmp is a case-sensitive version of _strnicmp. wcsncmp and _mbsncmp are case-sensitive versions of _wcsnicmp and _mbsnicmp.

wcsncmp and _mbsncmp are wide-character and multibyte-character versions of strncmp. The arguments and return value of wcsncmp are wide-character strings; those of _mbsncmp are multibyte-character strings. _mbsncmp recognizes multibyte-character sequences according to a multibyte code page and returns _NLSCMPERROR on an error.

Also, _mbsncmp validates its parameters. If string1 or string2 is a null pointer,the invalid parameter handler is invoked, as described in Parameter Validation . If execution is allowed to continue, _mbsncmp returns _NLSCMPERROR and sets errno to EINVAL. strncmp and wcsncmp do not validate their parameters. These three functions behave identically otherwise.

The output value is affected by the setting of the LC_CTYPE category setting of the locale; see setlocale for more information. The versions of these functions without the _l suffix use the current locale for this locale-dependent behavior; the versions with the _l suffix are identical except that they use the locale parameter passed in instead. For more information, see Locale.

Generic-Text Routine Mappings

TCHAR.H routine

_UNICODE & _MBCS not defined

_MBCS defined

_UNICODE defined

_tcsnccmp

strncmp

_mbsnbcmp

wcsncmp

_tcsncmp

strncmp

_mbsnbcmp

wcsncmp

_tccmp

Maps to macro or inline function

_mbsncmp

Maps to macro or inline function

n/a

n/a

_mbsncmp_l

n/a

Requirements

Routine

Required header

strncmp

<string.h>

wcsncmp

<string.h> or <wchar.h>

_mbsncmp, _mbsncmp_l

<mbstring.h>

For additional compatibility information, see Compatibility in the Introduction.

Example

// crt_strncmp.c
#include <string.h>
#include <stdio.h>

char string1[] = "The quick brown dog jumps over the lazy fox";
char string2[] = "The QUICK brown fox jumps over the lazy dog";

int main( void )
{
   char tmp[20];
   int result;
   printf( "Compare strings:\n      %s\n      %s\n\n",
           string1, string2 );
   printf( "Function:   strncmp (first 10 characters only)\n" );
   result = strncmp( string1, string2 , 10 );
   if( result > 0 )
      strcpy_s( tmp, sizeof(tmp), "greater than" );
   else if( result < 0 )
      strcpy_s( tmp, sizeof(tmp), "less than" );
   else
      strcpy_s( tmp, sizeof(tmp), "equal to" );
   printf( "Result:      String 1 is %s string 2\n\n", tmp );
   printf( "Function:   strnicmp _strnicmp (first 10 characters only)\n" );
   result = _strnicmp( string1, string2, 10 );
   if( result > 0 )
      strcpy_s( tmp, sizeof(tmp), "greater than" );
   else if( result < 0 )
      strcpy_s( tmp, sizeof(tmp), "less than" );
   else
      strcpy_s( tmp, sizeof(tmp), "equal to" );
   printf( "Result:      String 1 is %s string 2\n", tmp );
}

Compare strings:
      The quick brown dog jumps over the lazy fox
      The QUICK brown fox jumps over the lazy dog

Function:   strncmp (first 10 characters only)
Result:      String 1 is greater than string 2

Function:   strnicmp _strnicmp (first 10 characters only)
Result:      String 1 is equal to string 2

.NET Framework Equivalent

System::String::Compare

See Also

Concepts

String Manipulation (CRT)

Locale

Interpretation of Multibyte-Character Sequences

_mbsnbcmp, _mbsnbcmp_l

_mbsnbicmp, _mbsnbicmp_l

strcmp, wcscmp, _mbscmp

strcoll Functions

_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