Función CompareStringEx (stringapiset.h)

Artículo
08/26/2023

Compara dos cadenas Unicode (caracteres anchos), para una configuración regional especificada por nombre.

Precaución El uso de CompareStringEx incorrectamente puede poner en peligro la seguridad de la aplicación. Las cadenas que no se comparan correctamente pueden producir entradas no válidas. Pruebe las cadenas para asegurarse de que son válidas antes de usarlas y proporcione controladores de errores. Para obtener más información, vea Consideraciones de seguridad: Características internacionales.

Nota La aplicación debe llamar a esta función en preferencia a CompareString si está diseñada para ejecutarse solo en Windows Vista y versiones posteriores.

Sintaxis

int CompareStringEx(
  [in, optional] LPCWSTR                          lpLocaleName,
  [in]           DWORD                            dwCmpFlags,
  [in]           _In_NLS_string_(cchCount1)LPCWCH lpString1,
  [in]           int                              cchCount1,
  [in]           _In_NLS_string_(cchCount2)LPCWCH lpString2,
  [in]           int                              cchCount2,
  [in, optional] LPNLSVERSIONINFO                 lpVersionInformation,
  [in, optional] LPVOID                           lpReserved,
  [in, optional] LPARAM                           lParam
);

Parámetros

[in, optional] lpLocaleName

Puntero a un nombre de configuración regional o uno de los siguientes valores predefinidos.

[in] dwCmpFlags

Marcas que indican cómo la función compara las dos cadenas. De forma predeterminada, estas marcas no se establecen. Este parámetro puede especificar una combinación de cualquiera de los valores siguientes o se puede establecer en 0 para obtener el comportamiento predeterminado.

Marca	Significado
LINGUISTIC_IGNORECASE	Omita mayúsculas y minúsculas, según corresponda lingüísticamente.
LINGUISTIC_IGNOREDIACRITIC	Omita los caracteres sin espaciado, según corresponda lingüísticamente. Nota Esta marca no siempre genera resultados predecibles cuando se usan con caracteres descomponidos, es decir, caracteres en los que un carácter base y uno o varios caracteres sin espaciar cada uno tienen valores de punto de código distintos.
NORM_IGNORECASE	Omitir mayúsculas y minúsculas. Para muchos scripts (en particular los alfabetos latinos), NORM_IGNORECASE coincide con LINGUISTIC_IGNORECASE. Nota NORM_IGNORECASE omite cualquier distinción terciaria, ya sea en realidad lingüística o no. Por ejemplo, en los scripts árabes e indices, distingue las formas alternativas de un carácter, pero las diferencias no corresponden a mayúsculas y minúsculas lingüísticas. LINGUISTIC_IGNORECASE hace que la función ignore solo el uso de mayúsculas y minúsculas lingüísticas reales, en lugar de omitir el tercer peso de ordenación. Nota Con este conjunto de marcas, la función omite la distinción entre las formas anchas y estrechas de los caracteres de compatibilidad de CJK.
NORM_IGNOREKANATYPE	No diferencie entre los caracteres hiragana y katakana. Los caracteres hiragana y katakana correspondientes se comparan como iguales.
NORM_IGNORENONSPACE	Omitir caracteres sin espaciado. Para muchos scripts (en particular los alfabetos latinos), NORM_IGNORENONSPACE coincide con LINGUISTIC_IGNOREDIACRITIC. Nota NORM_IGNORENONSPACE omite cualquier distinción secundaria, ya sea diacrítico o no. Los scripts para idiomas coreanos, japoneses, chinos e indices, entre otros, usan esta distinción para fines distintos de los diacríticos. LINGUISTIC_IGNOREDIACRITIC hace que la función ignore solo los diacríticos reales, en lugar de omitir el segundo peso de ordenación. Nota NORM_IGNORENONSPACE solo tiene un efecto para las configuraciones regionales en las que los caracteres acentuados se ordenan en un segundo paso de caracteres principales. Normalmente, todos los caracteres de la cadena se comparan primero sin tener en cuenta los acentos y, si las cadenas son iguales, se realiza un segundo paso sobre las cadenas para comparar acentos. Esta marca hace que no se realice el segundo paso. En el caso de las configuraciones regionales que ordenan caracteres acentuados en el primer paso, esta marca no tiene ningún efecto.
NORM_IGNORESYMBOLS	Omitir símbolos y puntuación.
NORM_IGNOREWIDTH	Omita la diferencia entre los caracteres de ancho medio y ancho completo, por ejemplo, C a t == cat. El formulario de ancho completo es una distinción de formato utilizada en scripts chinos y japoneses.
NORM_LINGUISTIC_CASING	Use las reglas lingüísticas predeterminadas para mayúsculas y minúsculas, en lugar de las reglas del sistema de archivos. Tenga en cuenta que la mayoría de los escenarios de CompareStringEx usan esta marca. Esta marca no tiene que usarse cuando la aplicación llama a CompareStringOrdinal.
SORT_DIGITSASNUMBERS	Windows 7: Trate los dígitos como números durante la ordenación, por ejemplo, ordene "2" antes de "10".
SORT_STRINGSORT	Trate la puntuación igual que los símbolos.

[in] lpString1

Puntero a la primera cadena que se va a comparar.

[in] cchCount1

Longitud de la cadena indicada por lpString1, excepto el carácter nulo de terminación. La aplicación puede proporcionar un valor negativo si la cadena termina en null. En este caso, la función determina la longitud automáticamente.

[in] lpString2

Puntero a la segunda cadena que se va a comparar.

[in] cchCount2

Longitud de la cadena indicada por lpString2, excepto el carácter nulo de terminación. La aplicación puede proporcionar un valor negativo si la cadena termina en null. En este caso, la función determina la longitud automáticamente.

[in, optional] lpVersionInformation

Puntero a una estructura NLSVERSIONINFOEX que contiene la información de versión sobre la funcionalidad NLS pertinente; normalmente recuperado de GetNLSVersionEx.

Windows Vista, Windows 7: Reservados; debe establecerse en NULL.

[in, optional] lpReserved

Reservados; debe establecerse en NULL.

[in, optional] lParam

Reservados; debe establecerse en 0.

Valor devuelto

Devuelve uno de los valores siguientes si se ejecuta correctamente. Para mantener la convención de tiempo de ejecución de C de comparar cadenas, el valor 2 se puede restar de un valor devuelto distinto de cero. A continuación, el significado de <0, ==0 y >0 es coherente con el tiempo de ejecución de C.

CSTR_LESS_THAN. La cadena indicada por lpString1 es menor en el valor léxico que la cadena indicada por lpString2.
CSTR_EQUAL. La cadena indicada por lpString1 es equivalente en el valor léxico a la cadena indicada por lpString2. Las dos cadenas son equivalentes con fines de ordenación, aunque no necesariamente idénticas.
CSTR_GREATER_THAN. La cadena indicada por lpString1 es mayor en el valor léxico que la cadena indicada por lpString2.

La función devuelve 0 si no se realiza correctamente. Para obtener información de error extendida, la aplicación puede llamar a GetLastError, que puede devolver uno de los siguientes códigos de error:

ERROR_INVALID_FLAGS. Los valores proporcionados para las marcas no eran válidos.
ERROR_INVALID_PARAMETER. Cualquiera de los valores de parámetro no era válido.

Comentarios

CompareString y CompareStringEx están optimizados para ejecutarse a la máxima velocidad cuando dwCmpFlags se establece en 0 o NORM_IGNORECASE, cchCount1 y cchCount2 se establecen en -1 y la configuración regional no admite ninguna compresión lingüística, como cuando la ordenación tradicional española trata "ch" como un solo carácter.

CompareString y CompareStringEx omiten los kashidas árabes durante la comparación. Por lo tanto, si dos cadenas son idénticas excepto la presencia de kashidas, la función devuelve CSTR_EQUAL.

Cuando la aplicación usa las marcas NORM_IGNORENONSPACE y NORM_IGNORECASE con la función de ordenación, las marcas a veces pueden interferir con las comparaciones de cadenas. Esta situación puede dar lugar a una configuración regional que no admite caracteres sin espaciado o mayúsculas de minúsculas, pero usa niveles de peso equivalentes para controlar otras operaciones importantes. En tales casos, la aplicación debe usar las marcas LINGUISTIC_IGNOREDIACRITIC y LINGUISTIC_IGNORECASE. Estas marcas proporcionan resultados lingüísticos adecuados para ordenar puntos de código que usan mayúsculas y minúsculas y marcas diacríticas, y no tienen ningún impacto en otros puntos de código.

A partir de Windows Vista: CompareString y CompareStringEx pueden recuperar datos de configuraciones regionales personalizadas. No se garantiza que los datos sean los mismos desde el equipo al equipo o entre ejecuciones de una aplicación. Si la aplicación debe conservar o transmitir datos, consulte Uso de datos de configuración regional persistente.

A partir de Windows 8: si la aplicación pasa etiquetas de idioma a esta función desde el espacio de nombres Windows.Globalization, primero debe convertir las etiquetas llamando a ResolveLocaleName.

A partir de Windows 8: CompareStringEx se declara en Stringapiset.h. Antes de Windows 8, se declaró en Winnls.h.

Nota El comportamiento de la ordenación puede cambiar entre versiones de Windows. Por ejemplo, puede haber nuevos puntos de código Unicode creados. Use GetNlsVersionEx para detectar si la versión de ordenación ha cambiado.

Ejemplos

Puede encontrar un ejemplo que muestra el uso de esta función en NLS: Ejemplo de API basadas en nombres.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2008 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	stringapiset.h (incluye Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll