CompareStringA, fonction (winnls.h)

Article
08/27/2023

Compare deux chaînes de caractères, pour un paramètre régional spécifié par l’identificateur.

AttentionL’utilisation incorrecte de CompareString peut compromettre la sécurité de votre application. Les chaînes qui ne sont pas correctement comparées peuvent produire une entrée non valide. Par exemple, la fonction peut poser des problèmes de sécurité lorsqu’elle est utilisée pour une comparaison non linguistique, car deux chaînes distinctes dans leur représentation binaire peuvent être équivalentes sur le plan linguistique. L’application doit tester la validité des chaînes avant de les utiliser et doit fournir des gestionnaires d’erreurs. Pour plus d’informations, consultez Considérations relatives à la sécurité : fonctionnalités internationales.

Note Pour la compatibilité avec Unicode, vos applications doivent préférer CompareStringEx ou la version Unicode de CompareString. Une autre raison de préférer CompareStringEx est que Microsoft migre vers l’utilisation de noms de paramètres régionaux au lieu d’identificateurs régionaux pour les nouveaux paramètres régionaux, pour des raisons d’interopérabilité. Toute application qui sera exécutée uniquement sur Windows Vista et versions ultérieures doit utiliser CompareStringEx.

Syntaxe

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

Paramètres

[in] Locale

Identificateur des paramètres régionaux utilisés pour la comparaison. Vous pouvez utiliser la macro MAKELCID pour créer un identificateur de paramètres régionaux ou utiliser l’une des valeurs prédéfinies suivantes.

[in] dwCmpFlags

Indicateurs qui indiquent comment la fonction compare les deux chaînes. Pour obtenir des définitions détaillées, consultez le paramètre dwCmpFlags de CompareStringEx.

[in] lpString1

Pointeur vers la première chaîne à comparer.

[in] cchCount1

Longueur de la chaîne indiquée par lpString1, à l’exclusion du caractère null de fin. Cette valeur représente les octets de la version ANSI de la fonction et les caractères larges pour la version Unicode. L’application peut fournir une valeur négative si la chaîne se termine par un caractère Null. Dans ce cas, la fonction détermine automatiquement la longueur.

[in] lpString2

Pointeur vers la deuxième chaîne à comparer.

[in] cchCount2

Longueur de la chaîne indiquée par lpString2, à l’exclusion du caractère null de fin. Cette valeur représente les octets de la version ANSI de la fonction et les caractères larges pour la version Unicode. L’application peut fournir une valeur négative si la chaîne se termine par un caractère Null. Dans ce cas, la fonction détermine automatiquement la longueur.

Valeur retournée

Retourne les valeurs décrites pour CompareStringEx.

Remarques

Consultez les remarques relatives à CompareStringEx.

Si votre application appelle la version ANSI de CompareString, la fonction convertit les paramètres via la page de codes par défaut des paramètres régionaux fournis. Ainsi, une application ne peut jamais utiliser CompareString pour gérer du texte UTF-8.

Normalement, pour les comparaisons ne respectant pas la casse, CompareString mappe le « i » minuscule au « I » majuscule, même lorsque les paramètres régionaux sont turcs ou azerbaïdjanais. L’indicateur NORM_LINGUISTIC_CASING remplace ce comportement pour le turc ou l’azerbaïdjan. Si cet indicateur est spécifié conjointement avec le TURC ou l’Azerbaïdjan, LETTRE MINUSCULE LATINE POINTILLÉE I (U+0131) est la FORME MINUSCULE DE LETTRE MAJUSCULE LATINE I (U+0049) ET LETTRE MINUSCULE LATINE I (U+0069) EST LA FORME MINUSCULE DE LA LETTRE MAJUSCULE LATINE I POINT AU-DESSUS (U+0130).

À compter de Windows 8 : La version ANSI de la fonction est déclarée dans Winnls.h, et la version Unicode est déclarée dans Stringapiset.h. Avant Windows 8, les deux versions étaient déclarées dans Winnls.h.

Notes

L’en-tête winnls.h définit CompareString en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise


Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winnls.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll