Funzione CompareStringEx (stringapiset.h)

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

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.

• LOCALE_NAME_INVARIANT
• LOCALE_NAME_SYSTEM_DEFAULT
• LOCALE_NAME_USER_DEFAULT

[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.

[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.

• 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.

Esempio

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

Requisiti

Vedere anche

CompareString

Impostazioni locali personalizzate

Gestione dell'ordinamento nelle applicazioni

Supporto per la lingua nazionale

Funzioni di supporto del linguaggio nazionale

Considerazioni sulla sicurezza: funzionalità internazionali

Uso della normalizzazione Unicode per rappresentare stringhe