_mbsnbcoll, _mbsnbcoll_l, _mbsnbicoll, _mbsnbicoll_l

Artículo
06/09/2015

Compara n bytes de dos cadenas de caracteres multibyte usando la información de la página de códigos multibyte.

Importante

Esta API no se puede usar en aplicaciones que se ejecutan en Windows en tiempo de ejecución.Para obtener más información, vea Funciones de CRT no admitidas con /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
);

Parámetros

string1, string2
Cadenas que se van a comparar.
count
Número de bytes que se van a comparar.
locale
Configuración regional que se va a usar.

Valor devuelto

El valor devuelto indica la relación de las subcadenas de string1 y string2.

Valor devuelto	Descripción
< 0	La subcadena string1 es menor que la subcadena string2.
0	La subcadena string1 es idéntica a la subcadena string2.
> 0	La subcadena string1 es mayor que la subcadena string2.

Si string1 o string2 es NULL, o si count es mayor que INT_MAX, se invoca el controlador de parámetros no válidos, como se describe en Validación de parámetros. Si la ejecución puede continuar, estas funciones devuelven _NLSCMPERROR y establecen errno en EINVAL. Para usar _NLSCMPERROR, incluya String.h o Mbstring.h.

Comentarios

Cada una de estas funciones intercala, como máximo, los primeros count bytes de string1 y string2, y devuelve un valor que indica la relación entre las subcadenas resultantes de string1 y string2. Si el byte final de la subcadena de string1 o string2 es un byte inicial, no se incluye en la comparación; estas funciones solo comparan caracteres completos de las subcadenas. _mbsnbicoll es una versión sin distinción entre mayúsculas y minúsculas de _mbsnbcoll. Al igual que _mbsnbcmp y _mbsnbicmp, _mbsnbcoll y _mbsnbicoll intercalan las dos cadenas de caracteres multibyte según el orden lexicográfico especificado por la página de códigos multibyte que se esté usando.

En el caso de algunas páginas de códigos y los juegos de caracteres correspondientes, el orden de los caracteres del juego de caracteres no es igual que el orden lexicográfico de los caracteres. En la configuración regional de "C" no es así: el orden de los caracteres del juego de caracteres ASCII es igual que el orden lexicográfico de los caracteres. Sin embargo, en algunas páginas de códigos europeas, por ejemplo, el carácter “a” (valor 0x61) precede el carácter “ä” (valor 0xE4) en el juego de caracteres, pero el carácter “ä” precede el carácter “a” lexicográficamente. Para realizar una comparación lexicográfica de cadenas por bytes en un caso así, use _mbsnbcoll en lugar de _mbsnbcmp; para comprobar solo si las cadenas son iguales, use _mbsnbcmp.

Dado que las funciones coll intercalan lexicográficamente las cadenas para compararlas mientras que las funciones cmp prueban simplemente si las cadenas, las funciones coll son mucho más lentas que las versiones correspondientes de cmp. En consecuencia, las funciones coll solo se deben usar cuando el orden del juego de caracteres y el orden de los caracteres lexicográficos son distintos en la página de códigos actual, y la diferencia influye en la comparación.

El valor de salida se ve afectado por el valor de la categoría LC_CTYPE de la configuración regional; vea setlocale para obtener más información. Las versiones de estas funciones sin el sufijo _l usan la configuración regional actual de su comportamiento dependiente de la configuración regional; las versiones con el sufijo _l son idénticas salvo que usan el parámetro locale pasado en su lugar. Para obtener más información, vea Configuración regional.

Asignaciones de rutina de texto genérico

Rutina Tchar.h	_UNICODE y _MBCS no definidos	_MBCS definido	_UNICODE definido
_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