Funzione CompareStringA (winnls.h)

Articolo
11/20/2024

Confronta due stringhe di caratteri, per un impostazioni locali specificato dall'identificatore.

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

Nota Per 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 CompareStringA(
  [in] LCID   Locale,
  [in] DWORD  dwCmpFlags,
  [in] PCNZCH lpString1,
  [in] int    cchCount1,
  [in] PCNZCH lpString2,
  [in] int    cchCount2
);

Parametri

[in] Locale

identificatore delle impostazioni locali delle impostazioni locali usate per il confronto. È possibile utilizzare 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 le 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 di terminazione. Questo valore rappresenta i byte per la versione ANSI della funzione e i caratteri wide per la versione Unicode. L'applicazione può fornire un valore negativo se la stringa è con terminazione 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 di terminazione. Questo valore rappresenta i byte per la versione ANSI della funzione e i caratteri wide per la versione Unicode. L'applicazione può fornire un valore negativo se la stringa è con terminazione Null. In questo caso, la funzione determina automaticamente la lunghezza.

Valore restituito

Restituisce i valori descritti per CompareStringEx.

Osservazioni

Vedere la sezione 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.

In genere, per i confronti senza distinzione tra maiuscole e minuscole, CompareString esegue il mapping tra "i" minuscolo e "I" maiuscolo, anche quando le impostazioni locali sono turche o azere. Il flag NORM_LINGUISTIC_CASING sostituisce questo comportamento per turco o azero. Se questo flag viene specificato in combinazione con turco o azero, LATIN SMALL LETTER I (U+0131) è la forma minuscola della LETTERA MAIUSCOLA LATINA I (U+0049) e LATIN SMALL LETTER I (U+0069) è la forma minuscola della LETTERA MAIUSCOLA LATINA 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 è dichiarata in Stringapiset.h. Prima di Windows 8, entrambe le versioni sono state dichiarate in Winnls.h.

Nota

L'intestazione winnls.h definisce CompareString come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 2000 Professional [solo app desktop]
server minimo supportato	Windows 2000 Server [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	winnls.h (include Windows.h)
libreria	Kernel32.lib
dll	Kernel32.dll