Funzione CompareStringW (stringapiset.h)

Articolo
08/26/2023

Confronta due stringhe di caratteri, per le impostazioni locali specificate dall'identificatore.

Attenzione L'uso di CompareString in modo errato può compromettere la sicurezza dell'applicazione. Le stringhe non confrontate correttamente possono produrre input non validi. Ad esempio, la funzione può generare problemi di sicurezza quando viene usata per un confronto non linguistico, perché due stringhe distinte nella rappresentazione binaria possono essere equivalenti in modo linguistico. L'applicazione deve testare le stringhe per la validità prima di usarle e deve fornire gestori di errori. Per altre informazioni, vedere Considerazioni sulla sicurezza: Funzionalità internazionali.

Nota Per la compatibilità con Unicode, le applicazioni devono preferire CompareStringEx o la versione Unicode di CompareString. Un altro motivo per cui si preferisce CompareStringEx è che Microsoft sta eseguendo la migrazione verso l'uso dei nomi delle impostazioni locali anziché degli identificatori delle impostazioni locali per le nuove impostazioni locali, per motivi di interoperabilità. Qualsiasi applicazione che verrà eseguita solo in Windows Vista e versioni successive deve usare CompareStringEx.

Sintassi

int CompareStringW(
  [in] LCID                              Locale,
  [in] DWORD                             dwCmpFlags,
  [in] _In_NLS_string_(cchCount1)PCNZWCH lpString1,
  [in] int                               cchCount1,
  [in] _In_NLS_string_(cchCount2)PCNZWCH lpString2,
  [in] int                               cchCount2
);

Parametri

[in] Locale

Identificatore delle impostazioni locali usate per il confronto. È possibile usare la macro MAKELCID per creare un identificatore delle impostazioni locali o usare uno dei valori predefiniti seguenti.

[in] dwCmpFlags

Flag che indicano come la funzione confronta le due stringhe. Per definizioni dettagliate, vedere il parametro dwCmpFlags di CompareStringEx.

[in] lpString1

Puntatore alla prima stringa da confrontare.

[in] cchCount1

Lunghezza della stringa indicata da lpString1, escluso il carattere null terminante. Questo valore rappresenta i byte per la versione ANSI della funzione e dei caratteri wide per la versione Unicode. 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. Questo valore rappresenta i byte per la versione ANSI della funzione e dei caratteri wide per la versione Unicode. L'applicazione può fornire un valore negativo se la stringa è terminata con null. In questo caso, la funzione determina automaticamente la lunghezza.

Valore restituito

Restituisce i valori descritti per CompareStringEx.

Commenti

Vedere Osservazioni per CompareStringEx.

Se l'applicazione chiama la versione ANSI di CompareString, la funzione converte i parametri tramite la tabella codici predefinita delle impostazioni locali fornite. Pertanto, un'applicazione non può mai usare CompareString per gestire il testo UTF-8.

Normalmente, per i confronti senza distinzione tra maiuscole e minuscole, CompareString esegue il mapping dei caratteri minuscoli "i" alla "I" maiuscola, anche quando le impostazioni locali sono turche o azerbaijani. Il flag NORM_LINGUISTIC_CASING sostituisce questo comportamento per il turco o l'Azerbaijani. Se questo flag viene specificato in combinazione con turco o Azerbaijani, LATIN SMALL LETTER DOTLESS I (U+0131) è la forma minuscola di LETTERA MAIUSCOLA LATINA I (U+0049) e LATIN SMALL LETTER I (U+0069) è la forma minuscola della LETTERA MAIUSCOLA I CON PUNTO SOPRA (U+0130).

A partire da Windows 8: la versione ANSI della funzione viene dichiarata in Winnls.h e la versione Unicode viene dichiarata in Stringapiset.h. Prima di Windows 8, entrambe le versioni sono state dichiarate in Winnls.h.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	stringapiset.h (includere Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll