Función CompareStringA (winnls.h)

Artículo
11/20/2024

Compara dos cadenas de caracteres para un especificado por identificador.

precaución Usar CompareString incorrectamente puede poner en peligro la seguridad de la aplicación. Las cadenas que no se comparan correctamente pueden generar una entrada no válida. Por ejemplo, la función puede generar problemas de seguridad cuando se usa para una comparación no lingüística, ya que dos cadenas que son distintas en su representación binaria pueden ser lingüísticamente equivalentes. La aplicación debe probar cadenas de validez antes de usarlas y debe proporcionar controladores de errores. Para obtener más información, vea Consideraciones de seguridad: Características internacionales.

Nota Para la compatibilidad con Unicode, las aplicaciones deben preferir CompareStringEx o la versión Unicode de CompareString. Otro motivo para preferir CompareStringEx es que Microsoft está migrando hacia el uso de nombres de configuración regional en lugar de identificadores de configuración regional para nuevas configuraciones regionales, por motivos de interoperabilidad. Cualquier aplicación que se ejecute solo en Windows Vista y versiones posteriores debe usar CompareStringEx.

Sintaxis

int CompareStringA(
  [in] LCID   Locale,
  [in] DWORD  dwCmpFlags,
  [in] PCNZCH lpString1,
  [in] int    cchCount1,
  [in] PCNZCH lpString2,
  [in] int    cchCount2
);

Parámetros

[in] Locale

identificador de configuración regional de la configuración regional utilizada para la comparación. Puede usar la macro MAKELCID para crear un identificador de configuración regional o usar uno de los siguientes valores predefinidos.

[in] dwCmpFlags

Marcas que indican cómo la función compara las dos cadenas. Para obtener definiciones detalladas, consulte el parámetro dwCmpFlags de CompareStringEx.

[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. Este valor representa bytes para la versión ANSI de la función y caracteres anchos para la versión Unicode. La aplicación puede proporcionar un valor negativo si la cadena está terminada 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. Este valor representa bytes para la versión ANSI de la función y caracteres anchos para la versión Unicode. La aplicación puede proporcionar un valor negativo si la cadena está terminada en null. En este caso, la función determina la longitud automáticamente.

Valor devuelto

Devuelve los valores descritos para CompareStringEx.

Observaciones

Vea los comentarios de CompareStringEx.

Si la aplicación llama a la versión ANSI de CompareString, la función convierte los parámetros a través de la página de códigos predeterminada de la configuración regional proporcionada. Por lo tanto, una aplicación nunca puede usar CompareString para controlar el texto UTF-8.

Normalmente, para comparaciones que no distinguen mayúsculas de minúsculas, CompareString asigna la "i" minúscula a la "I" mayúscula, incluso cuando la configuración regional es turca o azerbaiyana. La marca NORM_LINGUISTIC_CASING invalida este comportamiento para turco o azerbaiyán. Si esta marca se especifica junto con Turco o Azerbaiyán, LATIN SMALL LETTER I (U+0131) es la forma minúscula de LATIN CAPITAL LETTER I (U+0049) y LATIN SMALL LETTER I (U+0069) es la forma en minúsculas de LATIN CAPITAL I WITH DOT ABOVE (U+0130).

a partir de Windows 8: La versión ANSI de la función se declara en Winnls.h y la versión Unicode se declara en Stringapiset.h. Antes de Windows 8, ambas versiones se declararon en Winnls.h.

Nota

El encabezado winnls.h define CompareString como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows 2000 Professional [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows 2000 Server [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	winnls.h (incluya Windows.h)
biblioteca de	Kernel32.lib
DLL de	Kernel32.dll