winnls.h


CompareString

La función CompareString compara dos cadenas de caracteres, usando las opciones locales especificadas por el identifiador dado como base para la comparación.

Sintaxis

int CompareString(
    LCID Locale,        // identificador de localización
    DWORD dwCmpFlags,   // opciones de estilo de comparación
    LPCTSTR lpString1,  // puntero a la primera cadena
    int cchCount1,      // tamaño, en bytes o caracteres, de la primera cadena
    LPCTSTR lpString2,  // puntero a la segunda cadena
    int cchCount2       // tamaño, en bytes o caracteres, de la segunda cadena
   );

Parámetros

Locale: especifica la localización usada para la comparación. Este parámetro puede se uno de los siguientes identificadores de localización predefinidos:

Valor Significado
LOCALE_SYSTEM_DEFAULT Localización del sistema por defecto.
LOCALE_USER_DEFAULT Localización del usuario actual por defecto.

Este parámetro puede ser también un identificador de localización creado por la macro MAKELCID.

dwCmpFlags: un conjunto de banderas que indican el modo en que la función compara las dos cadenas. Por defecto, estas banderas no está activas. Este parámetro puede espeficar cero para obtener el comportamiento por defecto, o puede ser una combinación de los siguientes valores:

Valor Significado
NORM_IGNORECASE Ignora diferencia entre mayúsculas y minúsculas.
NORM_IGNOREKANATYPE No hace distinciones entre caracteres Hiragana y Katakana. Los caracteres correspondientes Hiragana y Katakana se consideran iguales.
NORM_IGNORENONSPACE Ignora caracteres sin espacio.
NORM_IGNORESYMBOLS Ignora los símbolos.
NORM_IGNOREWIDTH No hace diferencias entre caracteres de un byte y el mismo carácter en dos bytes.
SORT_STRINGSORT Trata todos los caracteres de puntuación del mismo modo que los símbolos.

lpString1: apunta a la primera cadea a comparar.

cchCount1: especifica el tamaño, en bytes (versión ANSI) o caracteres (versión Unicode), de la cadena apuntada por el parámetro lpString1. Si este parámetro es -1, se asume que la cadena está terminada con nulo y la longitud se calcula automáticamente.

lpString2: apunta a la segunda cadena a comparar.

cchCount2: especifica el tamaño, en bytes (versión ANSI) o caracteres (versión Unicode), de la cadena apuntada por el parámetro lpString2. Si este parámetro es -1, se asume que la cadena está terminada con nulo y la longitud se calcula automáticamente.

Valor de retorno

Si la función tiene éxito, el valor de retorno es uno de los siguientes valores:

Valor Significado
1 La cadena apuntada por el parámetro lpString1 es menor en valor léxico que la cadena apuntada por el parámetro lpString2.
2 La cadena apuntada por lpString1 es igual en valor léxico que la cadena apuntada por lpString2.
3 la cadena apuntada por lpString1 es mayor en valor léxico que la apuntada por lpString2.

Si la función falla, el valor de retorno es cero. Para obtener información adicional sobre el error, llamar a GetLastError. GetLastError debe devolver uno de los siguientes códigos de error:

ERROR_INVALID_FLAGS
ERROR_INVALID_PARAMETER

Observaciones

Hay que tener en cuenta que si el valor de retorno es 3, las dos cadenas son "iguales" en sentido de comparación, pero no necesariamente idénticas.

Para mantener la convención de comparación de cadenas de las bibliotecas de C, se puede restar el valor 2 del valor de retorno no nulo. El significado < 0, ==0 y > 0 será entonces consistente con las funciones estándar C de comparación.

Si las dos cadenas no tienen longitudes diferentes, se comparan hasta lo longitud de la más corta. Si son iguales hasta ese punto, entonces el valor de retorno indicará que la cadena más larga es la mayor.

Generalmente, las cadenas se comparan usando una técnica llamada "word sort" (ordenación de palabras). En una word sort, todos los signos de puntuación y otros caracteres no alfanuméricos, excepto el guión y el apóstrofe, vienen antes que cualquier carácter alfanumérico. El guión y el apóstrofe se tratan de un modo diferente que el resto de los símbolos no alfanuméricos, de modo que se asegura que palabras como "coop" y "co-op" estén juntas dentro de una lista ordenada.

Si se especifica la bandera SORT_STRINGSORT, las cadenas se comparan usando la técnica llamada "string sort" (ordenación de cadenas). En una string sort, el guión y el apóstrofe se tratan del mismo modo que cualquier otro símbolo no alfanumérico: van detrás de los símbolos alfanuméricos.

La siguiente tabla muestra una lista de palabras ordenadas de las dos formas:

Word Sort String Sort Word Sort String Sort
billet bill's t-ant t-ant
bills billet tanya t-aria
bill's bills t-aria tanya
cannot can't sued sue's
cant cannot sues sued
can't cant sue's sues
con co-op went we're
coop con were went
co-op coop we're were

Las funciónes lstrcmp y lstrcmpi usan una ordenación de cadenas. Las funciones CompareString y LCMapString usan una comparación de palabras por defecto, pero pueden usar una ordenación de cadenas si son llamadas activando la bandera SORT_STRINGSORT.

La función CompareString está optimizada para ejecutarse a la velocidad más alta cuando dwCmpFlags usa el valor 0 o NORM_IGNORECASE, y tanto cchCount1 como cchCount2 usan el valor -1.

La función CompareString ignora Kashidas arábigas durante la comparación. Así que, si dos cadenas son idénticas salvo por la presencia de Kashidas, CompareString devuelve un valor de 2; las cadenas se consideran "iguales" en sentido de comparación, pero no son necesariamente idénticas.