_mbsnbcoll, _mbsnbcoll_l, _mbsnbicoll, _mbsnbicoll_l

Article
06/09/2015

Compare n octets de deux chaînes de caractères multi-octets en utilisant les informations de page de codes multi-octets.

Important

Cette API ne peut pas être utilisée dans les applications qui s'exécutent dans le Windows Runtime.Pour plus d'informations, consultez Fonctions CRT non prises en charge avec /ZW.

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
);

Paramètres

string1, string2
Chaînes à comparer.
count
Nombre d'octets à comparer.
locale
Paramètres régionaux à utiliser.

Valeur de retour

La valeur de retour indique la relation des sous-chaînes de string1 et string2.

Valeur de retour	Description
< 0	La sous-chaîne de string1 moins que la sous-chaîne de string2.
0	La sous-chaîne de string1 identique à la sous-chaîne de string2.
> 0	La sous-chaîne de string1 supérieure à la sous-chaîne de string2.

Si string1 ou string2 est NULL ou si count est plus grand que INT_MAX, le gestionnaire de paramètres non valides est appelé, comme décrit dans Validation de paramètre. Si l'exécution est autorisée à se poursuivre, ces fonctions retournent _NLSCMPERROR et définissent errno avec la valeur EINVAL. Pour utiliser _NLSCMPERROR, incluez STRING.h ou MBSTRING.h.

Notes

Chacune de ces fonctions assemble, au plus, les premiers octets count dans string1 et string2 et retourne une valeur indiquant la relation entre les sous-chaînes obtenues de string1 et string2. Si l'octet final dans la sous-chaîne de string1 ou de string2 est un octet de tête, il n'est pas inclus dans la comparaison ; ces fonctions comparent uniquement les caractères complets dans les sous-chaînes. _mbsnbicoll est une version de _mbsnbcoll ne tenant pas compte des majuscules et des minuscules. Comme _mbsnbcmp et _mbsnbicmp, _mbsnbcoll et _mbsnbicoll assemblent les deux chaînes de caractères multi-octets selon l'ordre lexicographique spécifié par la page de codes multi-octets en cours de utilisation.

Pour certaines pages de codes et les jeux de caractères correspondants, l'ordre des caractères dans le jeu de caractères peut différer de l'ordre des caractères lexicographiques. Dans les paramètres régionaux « C », ce n'est pas le cas : l'ordre des caractères dans le jeu de caractères ASCII est le même que l'ordre lexicographique des caractères. Toutefois, dans certaines pages de codes européennes, par exemple, le caractère « a » (valeur 0x61) précède le caractère « ä » (valeur 0xE4) dans le jeu de caractères, mais le caractère « ä » précède le caractère « a » lexicographiquement. Pour effectuer une comparaison lexicographique des chaînes par des octets dans une telle instance, utilisez _mbsnbcoll plutôt que _mbsnbcmp; pour vérifier que l'égalité de chaîne, utilisez _mbsnbcmp.

Les fonctions coll assemblent les chaînes lexicographiquement pour la comparaison, tandis que les fonctions cmp testent simplement l'égalité de chaîne, ainsi les fonctions coll sont beaucoup plus lentes que les versions correspondantes cmp. Par conséquent, les fonctions coll doivent être utilisées uniquement lorsqu'il existe une différence entre l'ordre du jeu de caractères et l'ordre des caractères lexicographiques dans la page de codes actuelle et que cette différence est intéressante pour la comparaison de chaînes.

La valeur de la sortie est affectée par la valeur du paramètre de la catégorie LC_CTYPE des paramètres régionaux ; consultez setlocale, pour plus d'informations. Les versions de ces fonctions sans le suffixe _l utilisent les paramètres régionaux pour ce comportement dépendant des paramètres régionaux ; les versions avec le suffixe _l sont identiques, sauf qu'elles utilisent à la place les paramètres régionaux transmis. Pour plus d'informations, consultez Paramètres régionaux.

Mappages de routines de texte générique

Routine Tchar.h	_UNICODE et _MBCS non définis	_MBCS défini	_UNICODE défini
_tcsncoll	_strncoll	_mbsnbcoll	_wcsncoll
_tcsncoll_l	_strncoll, _wcsncoll, _mbsncoll, _strncoll_l, _wcsncoll_l, _mbsncoll_l	_mbsnbcoll_l	_wcsncoll_l
_tcsnicoll	_strnicoll	_mbsnbicoll	_wcsnicoll
_tcsnicoll_l	_strnicoll_l	_mbsnbicoll_l	_wcsnicoll_l