_mbsnbcoll, _mbsnbcoll_l, _mbsnbicoll, _mbsnbicoll_l

Compara n bytes de duas cadeias de caracteres multibyte usando informações de página de código multibyte.

Importante

Esta API não pode ser usada 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 _mbsnbcoll(
   const unsigned char *string1,
   const unsigned char *string2,
   size_t count
);
int _mbsnbcoll_l(
   const unsigned char *string1,
   const unsigned char *string2,
   size_t count,
   _locale_t locale
);
int _mbsnbicoll(
   const unsigned char *string1,
   const unsigned char *string2,
   size_t count
);
int _mbsnbicoll_l(
   const unsigned char *string1,
   const unsigned char *string2,
   size_t count,
   _locale_t locale
);

Parâmetros

string1, string2
Cadeias de caracteres a serem comparadas.

count
Número de bytes a serem comparados.

locale
Localidade a usar.

Valor retornado

O valor retornado indica a relação das subcadeias de caracteres de string1 e string2.

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

Se string1 ou string2 for NULL ou count for maior que INT_MAX, o manipulador de parâmetro inválido será invocado, conforme descrito em Validação de parâmetro. Se a execução puder continuar, essas funções retornarão _NLSCMPERROR e definirão errno para EINVAL. Para usar _NLSCMPERROR, inclua String.h ou Mbstring.h.

Comentários

Cada uma dessas funções agrupa, no máximo, os primeiros count bytes em string1 e string2 retorna um valor indicando a relação entre as subcadeias de caracteres resultantes de string1 e string2. Se o byte final na subcadeia de caracteres de ou string2 for um byte principal, ele não será incluído na comparação; essas funções comparam apenas caracteres completos nas subcadeias de string1 caracteres. _mbsnbicoll é uma versão que não diferencia maiúsculas e minúsculas de _mbsnbcoll. Como _mbsnbcmp e _mbsnbicmp, _mbsnbcoll e _mbsnbicoll agrupam as duas cadeias de caracteres multibyte de acordo com a ordem lexicográfica especificada pela página de código multibyte em uso no momento.

Para algumas páginas de código e conjuntos de caracteres correspondente, a ordem dos caracteres no conjunto de caracteres pode diferir da ordem de caracteres lexicográfica. Na localidade "C", a ordem dos caracteres no conjunto de caracteres ASCII é a mesma que a ordem lexicográfica dos caracteres. No entanto, em algumas páginas de código europeias, por exemplo, o caractere “a” (valor 0x61) precede o caractere “ä” (valor 0xE4) no conjunto de caracteres, mas o caractere “ä” precede a caractere “a” lexicograficamente. Para realizar uma comparação lexicográfica de cadeias de caracteres por bytes em uma instância, use _mbsnbcoll em vez de _mbsnbcmp. Para verificar somente a igualdade de cadeia de caracteres, use _mbsnbcmp.

Como as funções coll agrupam as cadeias de caracteres lexicograficamente para comparação, enquanto as funções cmp simplesmente testam a igualdade da cadeia de caracteres, as funções coll são muito mais lentas do que as versões cmp correspondentes. Portanto, as coll funções devem ser usadas somente quando houver uma diferença entre a ordem do conjunto de caracteres e a ordem dos caracteres lexicográficos na página de código atual e essa diferença for de interesse para a comparação.

O valor de saída é afetado pela configuração da categoria LC_CTYPE da localidade. Para obter mais informações, consulte setlocale. As versões dessas funções sem o sufixo _l usam a localidade atual desse comportamento dependente da localidade. As versões com o sufixo _l são idênticas, exceto por usarem o parâmetro de localidade passado em seu lugar. Para obter mais informações, consulte Localidade.

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
_tcsncoll	_strncoll	_mbsnbcoll	_wcsncoll
_tcsncoll_l	_strncoll_l	_mbsnbcoll_l	_wcsncoll_l
_tcsnicoll	_strnicoll	_mbsnbicoll	_wcsnicoll
_tcsnicoll_l	_strnicoll_l	_mbsnbicoll_l	_wcsnicoll_l

Requisitos

Rotina	Cabeçalho necessário
_mbsnbcoll	<mbstring.h>
_mbsnbcoll_l	<mbstring.h>
_mbsnbicoll	<mbstring.h>
_mbsnbicoll_l	<mbstring.h>

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

Confira também

Manipulação de cadeia de caracteres
_mbsnbcat, _mbsnbcat_l
_mbsnbcmp, _mbsnbcmp_l
_mbsnbicmp, _mbsnbicmp_l
Funções strcoll
strncmp, wcsncmp, _mbsncmp, _mbsncmp_l
_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, , _mbsnicmp_l