Fonction CompareStringEx (stringapiset.h)

Article
08/26/2023

Compare deux chaînes Unicode (caractères larges), pour un paramètre régional spécifié par nom.

AttentionL’utilisation incorrecte de CompareStringEx 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. Testez les chaînes pour vous assurer qu’elles sont valides avant de les utiliser et fournissez des gestionnaires d’erreurs. Pour plus d’informations, consultez Considérations relatives à la sécurité : fonctionnalités internationales.

Note L’application doit appeler cette fonction de préférence à CompareString si elle est conçue pour s’exécuter uniquement sur Windows Vista et versions ultérieures.

Syntaxe

int CompareStringEx(
  [in, optional] LPCWSTR                          lpLocaleName,
  [in]           DWORD                            dwCmpFlags,
  [in]           _In_NLS_string_(cchCount1)LPCWCH lpString1,
  [in]           int                              cchCount1,
  [in]           _In_NLS_string_(cchCount2)LPCWCH lpString2,
  [in]           int                              cchCount2,
  [in, optional] LPNLSVERSIONINFO                 lpVersionInformation,
  [in, optional] LPVOID                           lpReserved,
  [in, optional] LPARAM                           lParam
);

Paramètres

[in, optional] lpLocaleName

Pointeur vers un nom de paramètres régionaux ou l’une des valeurs prédéfinies suivantes.

[in] dwCmpFlags

Indicateurs qui indiquent comment la fonction compare les deux chaînes. Par défaut, ces indicateurs ne sont pas définis. Ce paramètre peut spécifier une combinaison de l’une des valeurs suivantes, ou il peut être défini sur 0 pour obtenir le comportement par défaut.

Indicateur	Signification
LINGUISTIC_IGNORECASE	Ignorez la casse, selon le cas linguistiquement approprié.
LINGUISTIC_IGNOREDIACRITIC	Ignorez les caractères non espacés, selon le cas linguistiquement approprié. Note Cet indicateur ne produit pas toujours des résultats prévisibles lorsqu’il est utilisé avec des caractères décomposés, c’est-à-dire des caractères dans lesquels un caractère de base et un ou plusieurs caractères sans espacement ont chacun des valeurs de point de code distinctes.
NORM_IGNORECASE	Ignorer la casse. Pour de nombreux scripts (notamment les scripts latins), NORM_IGNORECASE coïncide avec LINGUISTIC_IGNORECASE. Note NORM_IGNORECASE ignore toute distinction tertiaire, qu’il s’agisse de cas linguistique ou non. Par exemple, dans les scripts arabes et indics, cela distingue d’autres formes d’un caractère, mais les différences ne correspondent pas à la casse linguistique. LINGUISTIC_IGNORECASE fait en sorte que la fonction ignore uniquement la casse linguistique réelle, au lieu d’ignorer le troisième poids de tri. Note Avec ce jeu d’indicateurs, la fonction ignore la distinction entre les formes larges et étroites des caractères de compatibilité CJK.
NORM_IGNOREKANATYPE	Ne faites pas de distinction entre les caractères hiragana et katakana. Les caractères hiragana et katakana correspondants sont égaux.
NORM_IGNORENONSPACE	Ignorez les caractères non espacés. Pour de nombreux scripts (notamment les scripts latins), NORM_IGNORENONSPACE coïncide avec LINGUISTIC_IGNOREDIACRITIC. Note NORM_IGNORENONSPACE ignore toute distinction secondaire, qu’il s’agisse d’un diacritique ou non. Les scripts pour les langues coréennes, japonaises, chinoises et indices, entre autres, utilisent cette distinction à des fins autres que diacritiques. LINGUISTIC_IGNOREDIACRITIC oblige la fonction à ignorer uniquement les diacritiques réels, au lieu d’ignorer le deuxième poids de tri. Note NORM_IGNORENONSPACE n’a d’effet que pour les paramètres régionaux dans lesquels les caractères accentués sont triés dans un deuxième passage de main caractères. Normalement, tous les caractères de la chaîne sont d’abord comparés sans tenir compte des accents et, si les chaînes sont égales, une deuxième passe sur les chaînes est effectuée pour comparer les accents. Cet indicateur empêche l’exécution de la deuxième passe. Pour les paramètres régionaux qui trient les caractères accentués dans la première passe, cet indicateur n’a aucun effet.
NORM_IGNORESYMBOLS	Ignorez les symboles et la ponctuation.
NORM_IGNOREWIDTH	Ignorez la différence entre les caractères demi-largeur et pleine largeur, par exemple, C a t == cat. Le formulaire pleine largeur est une distinction de mise en forme utilisée dans les scripts chinois et japonais.
NORM_LINGUISTIC_CASING	Utilisez les règles linguistiques par défaut pour la casse au lieu de règles de système de fichiers. Notez que la plupart des scénarios pour CompareStringEx utilisent cet indicateur. Cet indicateur n’a pas besoin d’être utilisé lorsque votre application appelle CompareStringOrdinal.
SORT_DIGITSASNUMBERS	Windows 7 : Traitez les chiffres comme des nombres pendant le tri, par exemple, triez « 2 » avant « 10 ».
SORT_STRINGSORT	Traitez la ponctuation comme des symboles.

[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. 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. 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, optional] lpVersionInformation

Pointeur vers une structure NLSVERSIONINFOEX qui contient les informations de version sur la fonctionnalité NLS pertinente ; généralement récupéré à partir de GetNLSVersionEx.

Windows Vista, Windows 7 : Réservés au; doit avoir la valeur NULL.

[in, optional] lpReserved

Réservés au; doit avoir la valeur NULL.

[in, optional] lParam

Réservés au; doit avoir la valeur 0.

Valeur retournée

Retourne l’une des valeurs suivantes en cas de réussite. Pour conserver la convention d’exécution C de comparaison de chaînes, la valeur 2 peut être soustraite d’une valeur de retour différente de zéro. Ensuite, la signification de <0, ==0 et >0 est cohérente avec le runtime C.

CSTR_LESS_THAN. La chaîne indiquée par lpString1 est moins en valeur lexicale que la chaîne indiquée par lpString2.
CSTR_EQUAL. La chaîne indiquée par lpString1 est équivalente en valeur lexicale à la chaîne indiquée par lpString2. Les deux chaînes sont équivalentes à des fins de tri, bien que pas nécessairement identiques.
CSTR_GREATER_THAN. La chaîne indiquée par lpString1 est supérieure en valeur lexicale à la chaîne indiquée par lpString2.

La fonction retourne 0 si elle ne réussit pas. Pour obtenir des informations d’erreur étendues, l’application peut appeler GetLastError, qui peut retourner l’un des codes d’erreur suivants :

ERROR_INVALID_FLAGS. Les valeurs fournies pour les indicateurs n’étaient pas valides.
ERROR_INVALID_PARAMETER. L’une des valeurs de paramètre n’était pas valide.

Remarques

CompareString et CompareStringEx sont tous deux optimisés pour s’exécuter à la vitesse la plus élevée lorsque dwCmpFlags est défini sur 0 ou NORM_IGNORECASE, que cchCount1 et cchCount2 sont définis sur -1 et que les paramètres régionaux ne prennent pas en charge les compressions linguistiques, comme lorsque le tri espagnol traditionnel traite « ch » comme un seul caractère.

CompareString et CompareStringEx ignorent les kashidas arabes pendant la comparaison. Ainsi, si deux chaînes sont identiques, à l’exception de la présence de kashidas, la fonction retourne CSTR_EQUAL.

Lorsque l’application utilise les indicateurs NORM_IGNORENONSPACE et NORM_IGNORECASE avec la fonction de tri, les indicateurs peuvent parfois interférer avec les comparaisons de chaînes. Cette situation peut se produire pour des paramètres régionaux qui ne prennent pas en charge les caractères non espacés ou la casse, mais qui utilisent des niveaux de poids équivalents pour gérer d’autres opérations importantes. Dans ce cas, votre application doit utiliser les indicateurs LINGUISTIC_IGNOREDIACRITIC et LINGUISTIC_IGNORECASE. Ces indicateurs fournissent des résultats linguistiquement appropriés pour trier les points de code qui utilisent des marques de casse et diacritiques, et n’ont aucun impact sur d’autres points de code.

À compter de Windows Vista : CompareString et CompareStringEx peuvent récupérer des données à partir de paramètres régionaux personnalisés. Il n’est pas garanti que les données soient identiques d’un ordinateur à l’autre ou entre les exécutions d’une application. Si votre application doit conserver ou transmettre des données, consultez Utilisation des données de paramètres régionaux persistants.

À compter de Windows 8 : si votre application transmet des balises de langue à cette fonction à partir de l’espace de noms Windows.Globalization, elle doit d’abord convertir les balises en appelant ResolveLocaleName.

À compter de Windows 8 : CompareStringEx est déclaré dans Stringapiset.h. Avant Windows 8, elle était déclarée dans Winnls.h.

Note Le comportement de tri peut changer d’une version windows à l’autre. Par exemple, de nouveaux points de code Unicode peuvent être créés. Utilisez GetNlsVersionEx pour découvrir si la version de tri a changé.

Exemples

Vous trouverez un exemple montrant l’utilisation de cette fonction dans NLS : Exemple d’API basées sur un nom.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	stringapiset.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll