CompareStringEx-Funktion (stringapiset.h)

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

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.

• LOCALE_NAME_INVARIANT
• LOCALE_NAME_SYSTEM_DEFAULT
• LOCALE_NAME_USER_DEFAULT

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

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

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

Beispiele

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

Anforderungen

Siehe auch

CompareString

Benutzerdefinierte Gebietsschemas

Behandeln der Sortierung in Ihren Anwendungen

Unterstützung für landessprachliche Sprachen

Unterstützungsfunktionen für nationalsprachliche Sprachen

Sicherheitsüberlegungen: Internationale Features

Verwenden der Unicode-Normalisierung zum Darstellen von Zeichenfolgen