CompareStringEx-Funktion (stringapiset.h)

Artikel
03/06/2024

Vergleicht zwei Unicode-Zeichenfolgen (Breitzeichen) für ein durch den Namen angegebenes Gebietsschema .

Vorsicht Die falsche Verwendung von CompareStringEx kann die Sicherheit Ihrer Anwendung beeinträchtigen. Zeichenfolgen, die nicht ordnungsgemäß verglichen werden, können ungültige Eingaben erzeugen. Testen Sie Zeichenfolgen, um sicherzustellen, dass sie gültig sind, bevor Sie sie verwenden, und stellen Sie Fehlerhandler bereit. Weitere Informationen finden Sie unter Sicherheitsüberlegungen: Internationale Features.

Hinweis Die Anwendung sollte diese Funktion vor CompareString aufrufen, wenn sie nur unter Windows Vista und höher ausgeführt werden soll.

Syntax

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

Parameter

[in, optional] lpLocaleName

Zeiger auf einen Gebietsschemanamen oder einen der folgenden vordefinierten Werte.

[in] dwCmpFlags

Flags, die angeben, wie die Funktion die beiden Zeichenfolgen vergleicht. Standardmäßig sind diese Flags nicht festgelegt. Dieser Parameter kann eine Kombination aus einem der folgenden Werte angeben, oder er kann auf 0 festgelegt werden, um das Standardverhalten zu erhalten.

Flag	Bedeutung
LINGUISTIC_IGNORECASE	Ignorieren Sie die Groß-/Kleinschreibung, linguistisch angemessen.
LINGUISTIC_IGNOREDIACRITIC	Ignorieren Sie nicht sprechende Zeichen, sofern linguistisch angemessen. Hinweis Dieses Flag erzeugt nicht immer vorhersagbare Ergebnisse, wenn es mit zerlegten Zeichen verwendet wird, d. h. Zeichen, in denen jeweils ein Basiszeichen und ein oder mehrere zeichenfreie Zeichen jeweils unterschiedliche Codepunktwerte aufweisen.
NORM_IGNORECASE	Groß-/Kleinschreibung ignorieren. Bei vielen Skripts (insbesondere lateinischen) fällt NORM_IGNORECASE mit LINGUISTIC_IGNORECASE zusammen. Hinweis NORM_IGNORECASE ignoriert jede tertiäre Unterscheidung, unabhängig davon, ob es sich tatsächlich um linguistische Fälle handelt oder nicht. In arabischen und indischen Schriften unterscheidet dies beispielsweise alternative Formen eines Zeichens, aber die Unterschiede entsprechen nicht dem linguistischen Fall. LINGUISTIC_IGNORECASE bewirkt, dass die Funktion nur die tatsächliche linguistische Groß- und Kleinschreibung ignoriert, anstatt die dritte Sortiergewichtung zu ignorieren. Hinweis Wenn dieses Flag festgelegt ist, ignoriert die Funktion die Unterscheidung zwischen den breiten und schmalen Formen der CJK-Kompatibilitätszeichen.
NORM_IGNOREKANATYPE	Unterscheiden Sie nicht zwischen Hiragana- und Katakana-Zeichen. Die entsprechenden Hiragana- und Katakana-Zeichen sind gleich.
NORM_IGNORENONSPACE	Ignorieren von Zeichen ohne Zeichenfolgen Bei vielen Skripts (insbesondere lateinischen) fällt NORM_IGNORENONSPACE mit LINGUISTIC_IGNOREDIACRITIC zusammen. Hinweis NORM_IGNORENONSPACE ignoriert jede sekundäre Unterscheidung, unabhängig davon, ob es sich um eine diakritische oder nicht handelt. Skripts für koreanische, japanische, chinesische und indische Sprachen verwenden diese Unterscheidung unter anderem für andere Zwecke als diakritische Zwecke. LINGUISTIC_IGNOREDIACRITIC bewirkt, dass die Funktion nur tatsächliche diakritische Zeichen ignoriert, anstatt die zweite Sortiergewichtung zu ignorieren. Hinweis NORM_IGNORENONSPACE wirkt sich nur auf Gebietsschemas aus, in denen Akzentzeichen in einem zweiten Durchlauf aus Standard Zeichen sortiert werden. Normalerweise werden zunächst alle Zeichen in der Zeichenfolge ohne Berücksichtigung von Akzenten verglichen, und wenn die Zeichenfolgen gleich sind, wird ein zweiter Pass über die Zeichenfolgen ausgeführt, um Akzente zu vergleichen. Dieses Flag bewirkt, dass der zweite Durchlauf nicht ausgeführt wird. Bei Gebietsschemas, die Akzentzeichen im ersten Durchlauf sortieren, hat dieses Flag keine Auswirkungen.
NORM_IGNORESYMBOLS	Ignorieren sie Symbole und Interpunktion.
NORM_IGNOREWIDTH	Ignorieren Sie den Unterschied zwischen Zeichen mit halber und voller Breite, z. B. C a t == cat. Die Form mit voller Breite ist eine Formatierungsunterscheidung, die in chinesischen und japanischen Skripts verwendet wird.
NORM_LINGUISTIC_CASING	Verwenden Sie die standardmäßigen linguistischen Regeln für die Groß- und Kleinschreibung anstelle von Dateisystemregeln. Beachten Sie, dass in den meisten Szenarien für CompareStringEx dieses Flag verwendet wird. Dieses Flag muss nicht verwendet werden, wenn Ihre Anwendung CompareStringOrdinal aufruft.
SORT_DIGITSASNUMBERS	Windows 7: Behandeln Sie Ziffern während der Sortierung als Zahlen, z. B. sortieren Sie "2" vor "10".
SORT_STRINGSORT	Behandeln Sie Interpunktion genauso wie Symbole.

[in] lpString1

Zeiger auf die erste zu vergleichende Zeichenfolge.

[in] cchCount1

Länge der durch lpString1 angegebenen Zeichenfolge, mit Ausnahme des abschließenden NULL-Zeichens. Die Anwendung kann einen negativen Wert angeben, wenn die Zeichenfolge NULL-beendet ist. In diesem Fall bestimmt die Funktion automatisch die Länge.

[in] lpString2

Zeiger auf die zweite zu vergleichende Zeichenfolge.

[in] cchCount2

Länge der durch lpString2 angegebenen Zeichenfolge, mit Ausnahme des abschließenden NULL-Zeichens. Die Anwendung kann einen negativen Wert angeben, wenn die Zeichenfolge NULL-beendet ist. In diesem Fall bestimmt die Funktion automatisch die Länge.

[in, optional] lpVersionInformation

Zeiger auf eine NLSVERSIONINFOEX-Struktur , die die Versionsinformationen zur relevanten NLS-Funktion enthält; wird in der Regel von GetNLSVersionEx abgerufen.

Windows Vista, Windows 7: Reserviert; muss auf NULL festgelegt werden.

[in, optional] lpReserved

Reserviert; muss auf NULL festgelegt werden.

[in, optional] lParam

Reserviert; muss auf 0 festgelegt werden.

Rückgabewert

Gibt bei erfolgreicher Ausführung einen der folgenden Werte zurück. Um die C-Laufzeitkonvention für den Vergleich von Zeichenfolgen beizubehalten, kann der Wert 2 von einem Rückgabewert ungleich null subtrahiert werden. Dann ist die Bedeutung von <0, ==0 und >0 mit der C-Runtime konsistent.

CSTR_LESS_THAN. Die durch lpString1 angegebene Zeichenfolge ist im lexikalischen Wert kleiner als die durch lpString2 angegebene Zeichenfolge.
CSTR_EQUAL. Die durch lpString1 angegebene Zeichenfolge entspricht im lexikalischen Wert der durch lpString2 angegebenen Zeichenfolge. Die beiden Zeichenfolgen sind zu Sortierungszwecken gleichwertig, aber nicht unbedingt identisch.
CSTR_GREATER_THAN. Die durch lpString1 angegebene Zeichenfolge ist im lexikalischen Wert größer als die durch lpString2 angegebene Zeichenfolge.

Die Funktion gibt 0 zurück, wenn sie nicht erfolgreich ist. Um erweiterte Fehlerinformationen zu erhalten, kann die Anwendung GetLastError aufrufen, wodurch einer der folgenden Fehlercodes zurückgegeben werden kann:

ERROR_INVALID_FLAGS. Die für Flags angegebenen Werte waren ungültig.
ERROR_INVALID_PARAMETER. Jeder der Parameterwerte war ungültig.

Hinweise

Sowohl CompareString als auch CompareStringEx sind so optimiert, dass sie mit der höchsten Geschwindigkeit ausgeführt werden, wenn dwCmpFlags auf 0 oder NORM_IGNORECASE festgelegt ist, cchCount1 und cchCount2 auf -1 festgelegt sind und das Gebietsschema keine linguistischen Komprimierungen unterstützt, wie wenn bei der herkömmlichen spanischen Sortierung "ch" als einzelnes Zeichen behandelt wird.

Sowohl CompareString als auch CompareStringEx ignorieren während des Vergleichs arabische Kashidas. Wenn also zwei Zeichenfolgen mit Ausnahme des Vorhandenseins von Kashidas identisch sind, gibt die Funktion CSTR_EQUAL zurück.

Wenn die Anwendung die NORM_IGNORENONSPACE und NORM_IGNORECASE Flags mit der Sortierfunktion verwendet, können die Flags manchmal Zeichenfolgenvergleiche beeinträchtigen. Dies kann zu einem Gebietsschema führen, das keine Nichtabstandszeichen oder Groß-/Kleinschreibung unterstützt, aber entsprechende Gewichtungsstufen verwendet, um andere wichtige Vorgänge zu verarbeiten. In solchen Fällen sollte Ihre Anwendung die flags LINGUISTIC_IGNOREDIACRITIC und LINGUISTIC_IGNORECASE verwenden. Diese Flags bieten linguistisch geeignete Ergebnisse für die Sortierung von Codepunkten, die Groß- und Kleinschreibung verwenden und keine Auswirkungen auf andere Codepunkte haben.

Ab Windows Vista: Sowohl CompareString als auch CompareStringEx können Daten aus benutzerdefinierten Gebietsschemas abrufen. Es ist nicht garantiert, dass die Daten von Computer zu Computer oder zwischen Ausführungen einer Anwendung identisch sind. Wenn Ihre Anwendung Daten beibehalten oder übertragen muss, finden Sie weitere Informationen unter Verwenden persistenter Gebietsschemadaten.

Ab Windows 8: Wenn Ihre App Sprachtags aus dem Windows.Globalization-Namespace an diese Funktion übergibt, muss sie zuerst die Tags konvertieren, indem ResolveLocaleName aufgerufen wird.

Ab Windows 8: CompareStringEx wird in Stringapiset.h deklariert. Vor Windows 8 wurde sie in Winnls.h deklariert.

Hinweis Das Verhalten der Sortierung kann sich zwischen Windows-Releases ändern. Beispielsweise können neue Unicode-Codepunkte erstellt werden. Verwenden Sie GetNlsVersionEx , um zu ermitteln, ob sich die Sortierversion geändert hat.

Beispiele

Ein Beispiel für die Verwendung dieser Funktion finden Sie unter NLS: Beispiel für namensbasierte APIs.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	stringapiset.h (Einschließen von Windows.h)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll