strncmp, wcsncmp, _mbsncmp, _mbsncmp_l

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

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.

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

Requisitos

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