CompareStringEx 函式 (stringapiset.h)
比較兩個 Unicode (寬字元) 字串，以依名稱指定的 地區 設定。
語法
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
);
參數
[in, optional] lpLocaleName
地區設定名稱的指標，或下列其中一個預先定義的值。
[in] dwCmpFlags
指出函式如何比較兩個字串的旗標。 根據預設，不會設定這些旗標。 此參數可以指定下列任何值的組合，也可以設定為0以取得預設行為。
| 旗標 | 意義 |
|---|---|
|
請視語言適當地忽略大小寫。 |
|
視語言適當地忽略非步調字元。
注意 當搭配分解字元使用時，此旗標不一定會產生可預測的結果，也就是說，基底字元和一或多個非步調字元各自具有相異字碼指標值的字元。
|
|
忽略大小寫。 對於許多腳本， (特別是拉丁腳本) ，NORM_IGNORECASE與LINGUISTIC_IGNORECASE一致。
注意 NORM_IGNORECASE會忽略任何第三個區別，不論其是否為語言大小寫。 例如，在阿拉伯文和索引腳本中，這會區分字元的替代形式，但差異不會對應至語言大小寫。 LINGUISTIC_IGNORECASE會導致函式只忽略實際的語言大小寫，而不是忽略第三個排序權數。
注意 設定此旗標后，函式會忽略 CJK 相容性字元的寬和窄格式之間的差異。
|
|
請勿區分平假名和片假名字符。 對應的平假名和片假名字符會比較為相等。 |
|
忽略非步調字元。 對於許多腳本， (拉丁腳本) ，NORM_IGNORENONSPACE與LINGUISTIC_IGNOREDIACRITIC一致。
注意 NORM_IGNORENONSPACE會忽略任何次要區別，不論是否為變音符號。 韓文、日文、中文和索引語言的腳本等，會針對讀音符號以外的用途使用此區別。 LINGUISTIC_IGNOREDIACRITIC會導致函式只忽略實際的變音符號，而不是忽略第二個排序權數。
注意 NORM_IGNORENONSPACE只有地區設定的效果，其中輔色字元會以主要字元的第二個階段排序。 一般而言，字串中的所有字元都會先進行比較，而不考慮輔色，如果字串相等，則會執行第二次傳遞字串來比較輔色。 此旗標會導致第二次傳遞無法執行。 對於在第一階段中排序強調字元的地區設定，此旗標不會有任何作用。
|
|
忽略符號和標點符號。 |
|
忽略半角和全角字元之間的差異，例如 C a t == cat。 全角表單是中文和日文腳本中使用的格式區分。 |
|
使用預設語言規則進行大小寫，而不是檔案系統規則。 請注意， CompareStringEx 的大部分案例都會使用此旗標。 當您的應用程式呼叫 CompareStringOrdinal 時，不需要使用此旗標。 |
|
Windows 7： 例如，在排序期間將數位視為數位，在 「10」 之前排序 「2」。。 |
|
將標點符號視為符號。 |
[in] lpString1
要比較之第一個字串的指標。
[in] cchCount1
lpString1 所指示的字串長度，不包括終止的 Null 字元。 如果字串是以 Null 終止，應用程式可以提供負值。 在此情況下，函式會自動判斷長度。
[in] lpString2
要比較之第二個字串的指標。
[in] cchCount2
lpString2 所指示的字串長度，不包括終止的 Null 字元。 如果字串是以 Null 終止，應用程式可以提供負值。 在此情況下，函式會自動判斷長度。
[in, optional] lpVersionInformation
NLSVERSIONINFOEX 結構的指標，其中包含相關 NLS 功能的版本資訊;通常從 GetNLSVersionEx 擷取。
Windows Vista、Windows 7： 保留;必須設定為 NULL。
[in, optional] lpReserved
保留;必須設定為 NULL。
[in, optional] lParam
保留;必須設定為 0。
傳回值
如果成功，則傳回下列其中一個值。 若要維護比較字串的 C 運行時間慣例，可以從非零傳回值減去值 2。 然後，0、==0 和 >0 的意義<與 C 運行時間一致。
- CSTR_LESS_THAN。 lpString1 所表示的字串在語彙值中小於 lpString2 所指示的字串。
- CSTR_EQUAL。 lpString1 所指示的字串相當於 lpString2 所指示的字串語彙值。 這兩個字串對等用於排序用途，但不一定相同。
- CSTR_GREATER_THAN。 lpString1 所表示的字串在語彙值中大於 lpString2 所指示的字串。
- ERROR_INVALID_FLAGS。 為旗標的值無效。
- ERROR_INVALID_PARAMETER。 任何參數值都無效。
備註
CompareString 和 CompareStringEx 都經過優化，可在 dwCmpFlags 設定為 0 或 NORM_IGNORECASE、cchCount1 和 cchCount2 設為 -1 時以最高速度執行，而且地區設定不支援任何語言壓縮，如同傳統西班牙文排序會將 “ch” 視為單一字元時。
CompareString 和 CompareStringEx 都會在比較期間忽略阿拉伯 Kashida。 因此，如果兩個字串相同，但kashida的存在除外，函式會傳回CSTR_EQUAL。
當應用程式使用NORM_IGNORENONSPACE和NORM_IGNORECASE旗標搭配排序函式時，旗標有時會干擾字串比較。 這種情況可能會導致地區設定不支援非間距字元或大小寫，但使用對等權數等級來處理其他重要作業。 在這種情況下，您的應用程式應該使用LINGUISTIC_IGNOREDIACRITIC和LINGUISTIC_IGNORECASE旗標。 這些旗標提供語言適當的結果，以便排序使用案例和讀音符號的程式代碼點，而且不會影響其他字碼點。
從 Windows Vista 開始： CompareString 和 CompareStringEx 都可以從自定義地區設定擷取數據。 數據不保證從計算機到計算機或在應用程式執行之間相同。 如果您的應用程式必須保存或傳輸數據，請參閱 使用持續性地區設定數據。
從 Windows 8 開始：如果您的 app 從 Windows.Globalization 命名空間將語言標籤傳遞至此函式，則必須先呼叫 ResolveLocaleName 來轉換標記。
從 Windows 8 開始：CompareStringEx 會在 Stringapiset.h 中宣告。 在 Windows 8 之前，它會在 Winnls.h 中宣告。
範例
此函式的使用範例可在 NLS：名稱型 API 範例中找到。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows Vista [傳統型應用程式 |UWP 應用程式] |
| 最低支援的伺服器 | Windows Server 2008 [傳統型應用程式 |UWP 應用程式] |
| 目標平台 | Windows |
| 標頭 | stringapiset.h (包含 Windows.h) |
| 程式庫 | Kernel32.lib |
| DLL | Kernel32.dll |
另請參閱
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應