_strncoll, _wcsncoll, _mbsncoll, _strncoll_l, _wcsncoll_l, _mbsncoll_l

Compara cadeias de caracteres usando informações específicas de localidade.

Importante

_mbsncoll e _mbsncoll_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 _strncoll(
   const char *string1,
   const char *string2,
   size_t count
);
int _wcsncoll(
   const wchar_t *string1,
   const wchar_t *string2,
   size_t count
);
int _mbsncoll(
   const unsigned char *string1,
   const unsigned char *string2,
   size_t count
);
int _strncoll_l(
   const char *string1,
   const char *string2,
   size_t count,
   _locale_t locale
);
int _wcsncoll_l(
   const wchar_t *string1,
   const wchar_t *string2,
   size_t count,
   _locale_t locale
);
int _mbsncoll_l(
   const unsigned char *string1,
   const unsigned char *string2,
   size_t count,
   _locale_t locale
);

Parâmetros

string1, string2
Cadeias de caracteres com terminação nula.

count
O número de caracteres a ser comparado.

locale
A localidade a ser usada.

Retornar valor

Cada uma dessas funções retorna um valor que indica a relação de subcadeias de caracteres de string1 e string2, da seguinte maneira.

Retornar valor	Relação de string1 com string2
< 0	string1 é menor que string2.
0	string1 é idêntico a string2.
> 0	string1 é maior que string2.

Cada uma dessas funções retorna _NLSCMPERROR. Para usar _NLSCMPERROR, inclua STRING.h ou MBSTRING.h. _wcsncoll pode falhar se string1 ou string2 contiverem códigos de caractere largo fora do domínio da sequência de agrupamento. Quando um erro ocorre, _wcsncoll pode definir errno para EINVAL. Para verificar se há um erro em uma chamada para _wcsncoll, defina errno como 0 e, em seguida, verifique errno após a _wcsncoll chamada.

Comentários

Cada uma dessas funções executa uma comparação que diferencia maiúsculas e minúsculas dos primeiros count caracteres em string1 e string2, de acordo com a página de código atualmente em uso. Use essas funções 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, e quando essa diferença for importante para a comparação da cadeia de caracteres. A ordem do conjunto de caracteres é dependente de localidade. As versões dessas funções que não têm o _l sufixo usam a localidade atual, mas as versões que têm o _l sufixo usam a localidade que é passada. Para obter mais informações, consulte Localidade.

Todas essas funções validam seus parâmetros. Se ou string1string2 for um ponteiro nulo ou count for maior que , o manipulador de parâmetros inválido será chamado, conforme descrito em Validação de INT_MAXparâmetro. Se a execução puder continuar, essas funções retornarão _NLSCMPERROR e definirão errno para EINVAL.

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

Mapeamentos de rotina de texto genérico

Rotina TCHAR.H	_UNICODE e _MBCS não definidos	_MBCS definido	_UNICODE definido
_tcsnccoll	_strncoll	_mbsncoll	_wcsncoll
_tcsncoll	_strncoll	_mbsnbcoll	_wcsncoll

Requisitos

Rotina	Cabeçalho necessário
_strncoll, _strncoll_l	<string.h>
_wcsncoll, _wcsncoll_l	<wchar.h> ou <string.h>
_mbsncoll, _mbsncoll_l	<mbstring.h>

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

Confira também

Localidade
Manipulação de cadeia de caracteres
Funções strcoll
localeconv
_mbsnbcoll, _mbsnbcoll_l, _mbsnbicoll, _mbsnbicoll_l
setlocale, _wsetlocale
strcmp, wcscmp, _mbscmp
_stricmp, _wcsicmp, _mbsicmp, _stricmp_l, _wcsicmp_l, _mbsicmp_l
strncmp, wcsncmp, _mbsncmp, _mbsncmp_l
_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l
strxfrm, wcsxfrm, _strxfrm_l, _wcsxfrm_l