Función CompareString (winnls.h)

Artículo
03/04/2024

Compara dos cadenas de caracteres para una configuración regional especificada por el identificador.

Precaución El uso de CompareString incorrectamente puede poner en peligro la seguridad de la aplicación. Las cadenas que no se comparan correctamente pueden producir entradas no válidas. 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 las 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. Otra razón 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 CompareString(
  [in] LCID    Locale,
  [in] DWORD   dwCmpFlags,
  [in] LPCTSTR lpString1,
  [in] int     cchCount1,
  [in] LPCTSTR 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 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. 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 termina en null. En este caso, la función determina la longitud automáticamente.

Valor devuelto

Devuelve los valores descritos para CompareStringEx.

Comentarios

Vea Comentarios para 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 azerbaiyano. Si esta marca se especifica junto con turco o azerbaiyano, LATÍN SMALL LETTER DOTLESS I (U+0131) es la forma minúscula de LETRA MAYÚSCULA LATINA I (U+0049) y LATIN SMALL LETTER I (U+0069) es la forma minúscula de LETRA MAYÚSCULA LATINA 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.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winnls.h (incluye Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll