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:

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:

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:

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:

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.