Compartilhar via

strncmp, wcsncmp, _mbsncmp, _mbsncmp_l

  • Artigo

Compara até a contagem especificada de caracteres de duas cadeias de caracteres.

Importante

_mbsncmp e _mbsncmp_l não podem ser usados em aplicativos executados no Windows Runtime. Para obter mais informações, confira Funções do CRT sem suporte em aplicativos da Plataforma Universal do Windows.

Sintaxe

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
);int _mbsnbcmp(
   const unsigned char *string1,
   const unsigned char *string2,
   size_t count
);

Parâmetros

string1, string2
Cadeias de caracteres a serem comparadas.

count
O número de caracteres a serem comparados.

locale
Localidade a usar.

Valor retornado

O valor retornado indica a relação das subcadeias de caracteres de string1 para string2 da seguinte maneira.

Valor retornado Descrição
< 0 string1 subcadeia de caracteres menor que string2 subcadeia de caracteres
0 string1 subcadeia de caracteres idêntica à string2 subcadeia de caracteres
> 0 string1 subcadeia de caracteres maior que string2 subcadeia de caracteres

Em um erro de validação de parâmetro, _mbsncmp e _mbsncmp_l retornam _NLSCMPERROR, que é definido em <string.h> e <mbstring.h>.

Comentários

A função strncmp executa uma comparação ordinal de, no máximo, os primeiros count caracteres em string1 e string2 e retorna um valor que indica a relação entre as subcadeias de caracteres. strncmp é uma versão que diferencia maiúsculas e minúsculas de _strnicmp. wcsncmp e _mbsncmp são versões que diferenciam maiúsculas e minúsculas de _wcsnicmp e _mbsnicmp.

wcsncmp e _mbsncmp são versões de caracteres largos e de caracteres multibyte de strncmp. Os argumentos de wcsncmp são cadeias de caracteres largos. Os argumentos de _mbsncmp são cadeias de caracteres multibyte. _mbsncmp reconhece sequências de caracteres multibyte de acordo com a página de código multibyte e retorna _NLSCMPERROR em um erro.

Além disso, _mbsncmp e _mbsncmp_l validam os parâmetros. Se string1 or string2 for um ponteiro nulo e count não for igual a 0, o manipulador de parâmetro inválido será invocado, conforme descrito em Validação de parâmetro. Se a execução tiver permissão para continuar, _mbsncmp e _mbsncmp_l retornarão _NLSCMPERROR e definirão errno como EINVAL. strncmp e wcsncmp não validam seus parâmetros. Caso contrário, essas funções se comportam de forma idêntica.

O comportamento de comparação de _mbsncmp e _mbsncmp_l é afetado pela configuração da LC_CTYPE configuração de categoria da localidade. Isso controla a detecção de bytes à esquerda e à direita de caracteres multibyte. Para obter mais informações, consulte setlocale. A função _mbsncmp usa a localidade atual para esse comportamento que depende da localidade. A função _mbsncmp_l é idêntica, exceto que usa o parâmetro locale, em vez disso. Para obter mais informações, consulte Localidade. Se a localidade for um byte único, o comportamento dessas funções será idêntico ao strncmp.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, confira Estado global no CRT.

Mapeamentos de rotina de texto genérico

Rotina TCHAR.H _UNICODE e _MBCS não definidos _MBCS definido _UNICODE definido
_tcsnccmp strncmp _mbsncmp wcsncmp
_tcsncmp strncmp _mbsnbcmp wcsncmp
_tccmp É mapeado para um macro ou uma função embutida _mbsncmp É mapeado para um macro ou uma função embutida

Requisitos

Rotina Cabeçalho necessário
strncmp <string.h>
wcsncmp <string.h> ou <wchar.h>
_mbsncmp, _mbsncmp_l <mbstring.h>

Para obter informações sobre compatibilidade, consulte Compatibilidade.

Exemplo

// 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

Confira também

Manipulação de cadeia de caracteres
Localidade
Interpretação de sequências de caracteres multibyte
_mbsnbcmp, _mbsnbcmp_l
_mbsnbicmp, _mbsnbicmp_l
strcmp, wcscmp, _mbscmp
Funções strcoll
_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