共用方式為


CompareStringEx 函式 (stringapiset.h)

比較兩個 Unicode (寬字元) 字串,以依名稱指定的 地區 設定。

謹慎 使用 CompareStringEx 不正確可能會危害應用程式的安全性。 未正確比較的字串可能會產生無效的輸入。 測試字串,以確定它們在使用之前有效,並提供錯誤處理程式。 如需詳細資訊,請參閱 安全性考慮:國際功能
 
注意 如果設計為只在 Windows Vista 和更新版本上執行,應用程式應該以喜好設定呼叫此函式至 CompareString
 

語法

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以取得預設行為。

旗標 意義
LINGUISTIC_IGNORECASE
請視語言適當地忽略大小寫。
LINGUISTIC_IGNOREDIACRITIC
視語言適當地忽略非步調字元。
注意 當搭配分解字元使用時,此旗標不一定會產生可預測的結果,也就是說,基底字元和一或多個非步調字元各自具有相異字碼指標值的字元。
 
NORM_IGNORECASE
忽略大小寫。 對於許多腳本, (特別是拉丁腳本) ,NORM_IGNORECASE與LINGUISTIC_IGNORECASE一致。
注意 NORM_IGNORECASE會忽略任何第三個區別,不論其是否為語言大小寫。 例如,在阿拉伯文和索引腳本中,這會區分字元的替代形式,但差異不會對應至語言大小寫。 LINGUISTIC_IGNORECASE會導致函式只忽略實際的語言大小寫,而不是忽略第三個排序權數。
 
注意 設定此旗標后,函式會忽略 CJK 相容性字元的寬和窄格式之間的差異。
 
NORM_IGNOREKANATYPE
請勿區分平假名和片假名字符。 對應的平假名和片假名字符會比較為相等。
NORM_IGNORENONSPACE
忽略非步調字元。 對於許多腳本, (拉丁腳本) ,NORM_IGNORENONSPACE與LINGUISTIC_IGNOREDIACRITIC一致。
注意 NORM_IGNORENONSPACE會忽略任何次要區別,不論是否為變音符號。 韓文、日文、中文和索引語言的腳本等,會針對讀音符號以外的用途使用此區別。 LINGUISTIC_IGNOREDIACRITIC會導致函式只忽略實際的變音符號,而不是忽略第二個排序權數。
 
注意 NORM_IGNORENONSPACE只有地區設定的效果,其中輔色字元會以主要字元的第二個階段排序。 一般而言,字串中的所有字元都會先進行比較,而不考慮輔色,如果字串相等,則會執行第二次傳遞字串來比較輔色。 此旗標會導致第二次傳遞無法執行。 對於在第一階段中排序強調字元的地區設定,此旗標不會有任何作用。
 
NORM_IGNORESYMBOLS
忽略符號和標點符號。
NORM_IGNOREWIDTH
忽略半角和全角字元之間的差異,例如 C a t == cat。 全角表單是中文和日文腳本中使用的格式區分。
NORM_LINGUISTIC_CASING
使用預設語言規則進行大小寫,而不是檔案系統規則。 請注意, CompareStringEx 的大部分案例都會使用此旗標。 當您的應用程式呼叫 CompareStringOrdinal 時,不需要使用此旗標。
SORT_DIGITSASNUMBERS
Windows 7: 例如,在排序期間將數位視為數位,在 「10」 之前排序 「2」。。
SORT_STRINGSORT
將標點符號視為符號。

[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 所指示的字串。
如果函式不成功,函式會傳回 0。 若要取得擴充的錯誤資訊,應用程式可以呼叫 GetLastError,這可以傳回下列其中一個錯誤碼:
  • ERROR_INVALID_FLAGS。 為旗標的值無效。
  • ERROR_INVALID_PARAMETER。 任何參數值都無效。

備註

CompareStringCompareStringEx 都經過優化,可在 dwCmpFlags 設定為 0 或 NORM_IGNORECASE、cchCount1 和 cchCount2 設為 -1 時以最高速度執行,而且地區設定不支援任何語言壓縮,如同傳統西班牙文排序會將 “ch” 視為單一字元時。

CompareStringCompareStringEx 都會在比較期間忽略阿拉伯 Kashida。 因此,如果兩個字串相同,但kashida的存在除外,函式會傳回CSTR_EQUAL。

當應用程式使用NORM_IGNORENONSPACE和NORM_IGNORECASE旗標搭配排序函式時,旗標有時會干擾字串比較。 這種情況可能會導致地區設定不支援非間距字元或大小寫,但使用對等權數等級來處理其他重要作業。 在這種情況下,您的應用程式應該使用LINGUISTIC_IGNOREDIACRITIC和LINGUISTIC_IGNORECASE旗標。 這些旗標提供語言適當的結果,以便排序使用案例和讀音符號的程式代碼點,而且不會影響其他字碼點。

從 Windows Vista 開始: CompareStringCompareStringEx 都可以從自定義地區設定擷取數據。 數據不保證從計算機到計算機或在應用程式執行之間相同。 如果您的應用程式必須保存或傳輸數據,請參閱 使用持續性地區設定數據

從 Windows 8 開始:如果您的 app 從 Windows.Globalization 命名空間將語言標籤傳遞至此函式,則必須先呼叫 ResolveLocaleName 來轉換標記。

從 Windows 8 開始:CompareStringEx 會在 Stringapiset.h 中宣告。 在 Windows 8 之前,它會在 Winnls.h 中宣告。

注意 排序的行為可以在 Windows 版本之間變更。 例如,可能會建立新的 Unicode 字碼點。 使用 GetNlsVersionEx 來探索排序版本是否已變更。
 

範例

此函式的使用範例可在 NLS:名稱型 API 範例中找到。

規格需求

需求
最低支援的用戶端 Windows Vista [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器 Windows Server 2008 [傳統型應用程式 |UWP 應用程式]
目標平台 Windows
標頭 stringapiset.h (包含 Windows.h)
程式庫 Kernel32.lib
DLL Kernel32.dll

另請參閱

CompareString

自訂地區設定

處理應用程式中的排序

國家語言支援

國家語言支援函式

安全性考慮:國際功能

使用 Unicode 正規化來表示字串