Share via


_mbsnbcmp, _mbsnbcmp_l

Compares the first n bytes of two multibyte-character strings.

Important

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

int _mbsnbcmp(
   const unsigned char *string1,
   const unsigned char *string2,
   size_t count 
);
int _mbsnbcmp_l(
   const unsigned char *string1,
   const unsigned char *string2,
   size_t count,
   _locale_t locale
);

Parameters

  • string1, string2
    The strings to compare.

  • count
    The number of bytes to compare.

  • locale
    The locale to use.

Return Value

The return value indicates the relationship between the substrings of string1 and string.

Return value

Description

< 0

string1 substring is less than string2 substring.

0

string1 substring is identical to string2 substring.

> 0

string1 substring is greater than string2 substring.

On an error, _mbsnbcmp returns _NLSCMPERROR, which is defined in String.h and Mbstring.h.

Remarks

The _mbsnbcmp function lexicographically compares, at most, the first count bytes in string1 and string2 and returns a value that indicates the relationship between the substrings. _mbsnbcmp is a case-sensitive version of _mbsnbicmp. Unlike strcoll, _mbsnbcmp is not affected by locale. _mbsnbcmp recognizes multibyte-character sequences according to the current multibyte code page.

_mbsnbcmp resembles _mbsncmp, except that _mbsncmp compares strings by characters rather than by bytes.

The output value is affected by the LC_CTYPE category setting of the locale; see setlocale for more information. The version of this function that doesn't have the _l suffix uses the current locale for this locale-dependent behavior; the version that has the _l suffix is identical except that it uses the locale parameter that's passed in instead. For more information, see Locale.

If either string1 or string2 is a null pointer, this function invokes the invalid parameter handler, as described in Parameter Validation. If execution is allowed to continue, the function returns _NLSCMPERROR and errno is set to EINVAL.

Generic-Text Routine Mappings

Tchar.h routine

_UNICODE and _MBCS not defined

_MBCS defined

_UNICODE defined

_tcsncmp

strncmp

_mbsnbcmp

wcsncmp

_tcsncmp_l

strncmp

_mbsnbcml

wcsncmp

Requirements

Routine

Required header

_mbsnbcmp

<mbstring.h>

_mbsnbcmp_l

<mbstring.h>

For more compatibility information, see Compatibility.

Example

// crt_mbsnbcmp.c
#include <mbstring.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", string1 );
   printf( "          %s\n\n", string2 );
   printf( "Function: _mbsnbcmp (first 10 characters only)\n" );
   result = _mbsncmp( string1, string2 , 10 );
   if( result > 0 )
      _mbscpy_s( tmp, sizeof(tmp), "greater than" );
   else if( result < 0 )
      _mbscpy_s( tmp, sizeof(tmp), "less than" );
   else
      _mbscpy_s( tmp, sizeof(tmp), "equal to" );
   printf( "Result:   String 1 is %s string 2\n\n", tmp );
   printf( "Function: _mbsnicmp _mbsnicmp (first 10 characters only)\n" );
   result = _mbsnicmp( string1, string2, 10 );
   if( result > 0 )
      _mbscpy_s( tmp, sizeof(tmp), "greater than" );
   else if( result < 0 )
      _mbscpy_s( tmp, sizeof(tmp), "less than" );
   else
      _mbscpy_s( tmp, sizeof(tmp), "equal to" );
   printf( "Result:   String 1 is %s string 2\n\n", tmp );
}

Output

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

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

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

.NET Framework Equivalent

Not applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.

See Also

Reference

String Manipulation (CRT)

_mbsnbcat, _mbsnbcat_l

_mbsnbicmp, _mbsnbicmp_l

strncmp, wcsncmp, _mbsncmp, _mbsncmp_l

_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l

Locale

Interpretation of Multibyte-Character Sequences