Fonction CompareString (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 soulever 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 linguistiquement équivalentes. 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 CompareString(
  [in] LCID    Locale,
  [in] DWORD   dwCmpFlags,
  [in] LPCTSTR lpString1,
  [in] int     cchCount1,
  [in] LPCTSTR 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 des octets pour la version ANSI de la fonction et des caractères larges pour la version Unicode. L’application peut fournir une valeur négative si la chaîne est terminée par 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 des octets pour la version ANSI de la fonction et des caractères larges pour la version Unicode. L’application peut fournir une valeur négative si la chaîne est terminée par null. Dans ce cas, la fonction détermine automatiquement la longueur.

Valeur retournée

Retourne les valeurs décrites pour CompareStringEx.

Remarques

Consultez Remarques pour CompareStringEx.

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

Normalement, pour les comparaisons sans respect de la casse, CompareString mappe le « i » minuscule à la majuscule « I », même si 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 DOTLESS I (U+0131) est la FORME MINUSCULE DE LA LETTRE MAJUSCULE LATINE I (U+0049) et LETTRE MINUSCULE LATINE I (U+0069) EST LA FORME MINUSCULE DE LA LETTRE MAJUSCULE LATINE I AVEC 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.

Configuration requise

Condition requise	Valeur
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