Funzione CompareStringEx (stringapiset.h)

Articolo
03/05/2024

Confronta due stringhe Unicode (carattere wide), per le impostazioni locali specificate in base al nome.

Attenzione L'uso di CompareStringEx in modo errato può compromettere la sicurezza dell'applicazione. Le stringhe non confrontate correttamente possono produrre input non validi. Testare le stringhe per assicurarsi che siano valide prima di usarle e fornire gestori di errori. Per altre informazioni, vedere Considerazioni sulla sicurezza: Funzionalità internazionali.

Nota L'applicazione deve chiamare questa funzione in preferenza per CompareString se progettata per l'esecuzione solo in Windows Vista e versioni successive.

Sintassi

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
);

Parametri

[in, optional] lpLocaleName

Puntatore a un nome delle impostazioni locali o uno dei valori predefiniti seguenti.

[in] dwCmpFlags

Flag che indicano come la funzione confronta le due stringhe. Per impostazione predefinita, questi flag non sono impostati. Questo parametro può specificare una combinazione di uno dei valori seguenti oppure può essere impostato su 0 per ottenere il comportamento predefinito.

Contrassegno	Significato
LINGUISTIC_IGNORECASE	Ignorare il caso, come appropriato in modo linguistico.
LINGUISTIC_IGNOREDIACRITIC	Ignorare i caratteri nonpacing, come appropriato in modo linguistico. Nota Questo flag non produce sempre risultati prevedibili quando viene usato con caratteri decomposti, ovvero caratteri in cui un carattere di base e uno o più caratteri non crittografati hanno valori di punto di codice distinti.
NORM_IGNORECASE	Ignorare il caso. Per molti script (in particolare script latini), NORM_IGNORECASE coincide con LINGUISTIC_IGNORECASE. Nota NORM_IGNORECASE ignora qualsiasi distinzione terziaria, indipendentemente dal fatto che sia effettivamente un caso linguistico o meno. Ad esempio, negli script arabi e indic, questo distingue le forme alternative di un carattere, ma le differenze non corrispondono al caso linguistico. LINGUISTIC_IGNORECASE causa l'ignorare solo le maiuscole e minuscole linguistiche effettive, anziché ignorare il terzo peso di ordinamento. Nota Con questo set di flag, la funzione ignora la distinzione tra le forme wide e strette dei caratteri di compatibilità CJK.
NORM_IGNOREKANATYPE	Non distinguere tra i caratteri hiragana e katakana. I caratteri hiragana e katakana corrispondenti vengono confrontati come uguali.
NORM_IGNORENONSPACE	Ignorare i caratteri nonpacing. Per molti script (in particolare script latini), NORM_IGNORENONSPACE coincide con LINGUISTIC_IGNOREDIACRITIC. Nota NORM_IGNORENONSPACE ignora qualsiasi distinzione secondaria, indipendentemente dal fatto che sia un diacritico o meno. Gli script per lingue coreane, giapponesi, cinesi e indic, tra gli altri, usano questa distinzione per scopi diversi da diacritici. LINGUISTIC_IGNOREDIACRITIC causa l'ignorare solo i diacritici effettivi anziché ignorare il secondo peso di ordinamento. Nota NORM_IGNORENONSPACE ha un effetto solo per le impostazioni locali in cui i caratteri accentati vengono ordinati in un secondo passaggio dai caratteri principali. In genere tutti i caratteri della stringa vengono confrontati senza considerare i accenti e, se le stringhe sono uguali, viene eseguito un secondo passaggio sulle stringhe per confrontare i accenti. Questo flag causa l'esecuzione del secondo passaggio. Per le impostazioni locali che ordinano caratteri accentati nel primo passaggio, questo flag non ha alcun effetto.
NORM_IGNORESYMBOLS	Ignorare i simboli e la punteggiatura.
NORM_IGNOREWIDTH	Ignorare la differenza tra caratteri a metà larghezza e larghezza intera, ad esempio C a t == cat. Il formato full-width è una distinzione di formattazione usata negli script cinesi e giapponesi.
NORM_LINGUISTIC_CASING	Usare le regole linguistiche predefinite per le maiuscole e minuscole anziché le regole del file system. Si noti che la maggior parte degli scenari per CompareStringEx usa questo flag. Questo flag non deve essere usato quando l'applicazione chiama CompareStringOrdinal.
SORT_DIGITSASNUMBERS	Windows 7: Considerare le cifre come numeri durante l'ordinamento, ad esempio ordinare "2" prima di "10".
SORT_STRINGSORT	Trattare la punteggiatura uguale ai simboli.

[in] lpString1

Puntatore alla prima stringa da confrontare.

[in] cchCount1

Lunghezza della stringa indicata da lpString1, escluso il carattere null terminante. L'applicazione può fornire un valore negativo se la stringa è terminata con null. In questo caso, la funzione determina automaticamente la lunghezza.

[in] lpString2

Puntatore alla seconda stringa da confrontare.

[in] cchCount2

Lunghezza della stringa indicata da lpString2, escluso il carattere null terminante. L'applicazione può fornire un valore negativo se la stringa è terminata con null. In questo caso, la funzione determina automaticamente la lunghezza.

[in, optional] lpVersionInformation

Puntatore a una struttura NLSVERSIONINFOEX che contiene le informazioni sulla versione relative alla funzionalità NLS pertinente; in genere recuperato da GetNLSVersionEx.

Windows Vista, Windows 7: Riservati; deve impostare su NULL.

[in, optional] lpReserved

Riservati; deve impostare su NULL.

[in, optional] lParam

Riservati; deve essere impostato su 0.

Valore restituito

Restituisce uno dei valori seguenti se ha esito positivo. Per mantenere la convenzione di runtime C delle stringhe di confronto, il valore 2 può essere sottratto da un valore restituito diverso da zero. Il significato di <0, ==0 e >0 è quindi coerente con il runtime C.

CSTR_LESS_THAN. La stringa indicata da lpString1 è minore del valore lessicale rispetto alla stringa indicata da lpString2.
CSTR_EQUAL. La stringa indicata da lpString1 è equivalente al valore lessicale alla stringa indicata da lpString2. Le due stringhe sono equivalenti ai fini dell'ordinamento, anche se non necessariamente identiche.
CSTR_GREATER_THAN. La stringa indicata da lpString1 è maggiore del valore lessicale rispetto alla stringa indicata da lpString2.

La funzione restituisce 0 se non riesce. Per ottenere informazioni sull'errore estese, l'applicazione può chiamare GetLastError, che può restituire uno dei codici di errore seguenti:

ERROR_INVALID_FLAGS. I valori forniti per i flag non sono validi.
ERROR_INVALID_PARAMETER. Uno dei valori dei parametri non è valido.

Commenti

Sia CompareString che CompareStringEx sono ottimizzati per l'esecuzione alla massima velocità quando dwCmpFlags è impostato su 0 o NORM_IGNORECASE, cchCount1 e cchCount2 sono impostati su -1 e le impostazioni locali non supportano alcuna compressione linguistica, come quando l'ordinamento tradizionale spagnolo considera "ch" come un singolo carattere.

Sia CompareString che CompareStringEx ignorano gli kashida arabi durante il confronto. Pertanto, se due stringhe sono identiche, ad eccezione della presenza di kashidas, la funzione restituisce CSTR_EQUAL.

Quando l'applicazione usa i flag NORM_IGNORENONSPACE e NORM_IGNORECASE con la funzione di ordinamento, i flag possono talvolta interferire con i confronti di stringhe. Questa situazione potrebbe comportare un'impostazione locale che non supporta caratteri di spaziatura o maiuscole/minuscole, ma usa livelli di peso equivalenti per gestire altre operazioni importanti. In questi casi, l'applicazione deve usare i flag di LINGUISTIC_IGNOREDIACRITIC e LINGUISTIC_IGNORECASE. Questi flag forniscono risultati linguisticamente appropriati per l'ordinamento dei punti di codice che usano segni di maiuscole e minuscole e non hanno alcun impatto su altri punti di codice.

A partire da Windows Vista: Sia CompareString che CompareStringEx possono recuperare i dati dalle impostazioni locali personalizzate. I dati non sono garantiti come uguali da computer a computer o tra esecuzioni di un'applicazione. Se l'applicazione deve mantenere o trasmettere dati, vedere Uso di dati locali persistenti.

A partire da Windows 8: se l'app passa tag di lingua a questa funzione dallo spazio dei nomi Windows.Globalization, deve prima convertire i tag chiamando ResolveLocaleName.

A partire da Windows 8: CompareStringEx è dichiarato in Stringapiset.h. Prima di Windows 8, è stato dichiarato in Winnls.h.

Nota Il comportamento dell'ordinamento può cambiare tra le versioni di Windows. Ad esempio, potrebbero essere creati nuovi punti di codice Unicode. Usare GetNlsVersionEx per individuare se la versione di ordinamento è stata modificata.

Esempio

Un esempio che mostra l'uso di questa funzione è disponibile in NLS: Esempio di API basate su nome.

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista [app desktop \| App UWP]
Server minimo supportato	Windows Server 2008 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	stringapiset.h (includere Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll