2 out of 4 rated this helpful - Rate this topic

strncmp, wcsncmp, _mbsncmp

Visual Studio .NET 2003

Compare characters of two strings.

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 
);

Parameters

string1, string2: Strings to compare.
count: Number of characters to compare.

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. Unlike strcoll, strncmp is not affected by locale. For more information on the LC_COLLATE category, see setlocale.

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 the current multibyte code page and returns _NLSCMPERROR on an error. For more information, see Code Pages. These three functions behave identically otherwise. wcsncmp and _mbsncmp are case-sensitive versions of _wcsnicmp and _mbsnicmp.

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

Requirements

Routine	Required header	Compatibility
strncmp	<string.h>	ANSI, Win 98, Win Me, Win NT, Win 2000, Win XP
wcsncmp	<string.h> or <wchar.h>	ANSI, Win 98, Win Me, Win NT, Win 2000, Win XP
_mbsncmp	<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_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( tmp, "greater than" );
   else if( result < 0 )
      strcpy( tmp, "less than" );
   else
      strcpy( 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( tmp, "greater than" );
   else if( result < 0 )
      strcpy( tmp, "less than" );
   else
      strcpy( tmp, "equal to" );
   printf( "Result:      String 1 is %s string 2\n", tmp );
}

Output

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