共用方式為


LCMapStringEx 函式 (winnls.h)

針對依名稱指定的地區設定,使用指定的轉換將輸入字元字串對應到另一個地區設定,或產生輸入字串的排序索引鍵。

注意 如果設計為只在 Windows Vista 和更新版本上執行,應用程式應該優先呼叫 此函式給 LCMapString

 

語法

int LCMapStringEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwMapFlags,
  [in]            LPCWSTR          lpSrcStr,
  [in]            int              cchSrc,
  [out, optional] LPWSTR           lpDestStr,
  [in]            int              cchDest,
  [in, optional]  LPNLSVERSIONINFO lpVersionInformation,
  [in, optional]  LPVOID           lpReserved,
  [in, optional]  LPARAM           sortHandle
);

參數

[in, optional] lpLocaleName

地區設定名稱的指標,或下列其中一個預先定義的值。

[in] dwMapFlags

旗標,指定要在字串對應期間使用的轉換類型,或要產生的排序索引鍵類型。 此參數可以有下列值。

旗標 意義
LCMAP_BYTEREV 使用位元組反轉。 例如,如果應用程式傳入0x3450 0x4822,結果就會0x5034 0x2248。
LCMAP_FULLWIDTH 如果適用,請使用 Unicode (寬) 字元。 此旗標和LCMAP_HALFWIDTH互斥。 使用此旗標時,即使輸入字元已經滿角,對應也可以使用正規化表單 C。 例如,字串 "は゛" (這已經是全形) 會正規化為 "ば"。 請參閱 Unicode 正規化格式
LCMAP_HALFWIDTH 如果適用,請使用窄字元。 此旗標和LCMAP_FULLWIDTH互斥。
LCMAP_HIRAGANA 將所有片假名字符對應到平假名。 此旗標和LCMAP_KATAKANA互斥。
LCMAP_KATAKANA 將所有平假名字符對應到片假名。 此旗標和LCMAP_HIRAGANA互斥。
LCMAP_LINGUISTIC_CASING 使用語言規則進行大小寫,而不是文件系統規則, (預設) 。 此旗標僅適用於LCMAP_LOWERCASE或LCMAP_UPPERCASE。
LCMAP_LOWERCASE 對於能夠處理大寫和小寫的地區設定和腳本,請將所有字元對應到小寫。
LCMAP_HASH 傳回字串原始排序權數的哈希。

出現的字串通常會傳回相同的哈希 (,例如“hello” 和 “HELLO” 與 LCMAP_IGNORECASE) 。 不過,某些複雜的案例,例如東亞語言,可以有與相同權數比較但不會傳回相同哈希的類似字串。

LCMAP_HASH要求輸出緩衝區的大小為 sizeof (int)
LCMAP_SIMPLIFIED_CHINESE 將繁體中文字元對應至簡體中文字元。 此旗標和LCMAP_TRADITIONAL_CHINESE互斥。
LCMAP_SORTHANDLE
使用排序句柄會導致效能降低,不建議使用。
傳回標記,代表地區設定 (解析的排序參數,例如地區設定名稱) ,因此未來的呼叫可以傳遞 NULL 排序名稱,並將先前查詢的排序句柄當做最後一個參數傳遞, (sortHandle) 後續對 CompareStringExLCMapStringEx 的呼叫。

LCMAP_SORTHANDLE要求輸出緩衝區的大小為 sizeof (lparam)
LCMAP_SORTKEY 產生標準化排序索引鍵。 如果未指定LCMAP_SORTKEY旗標,函式會執行字串對應。 如需排序索引鍵產生和字串對應的詳細數據,請參閱一節。
LCMAP_TITLECASE Windows 7: 將所有字元對應至標題大小寫,其中每個主要字的第一個字母都會大寫。
LCMAP_TRADITIONAL_CHINESE 將簡體中文字元對應至繁體中文字元。 此旗標和LCMAP_SIMPLIFIED_CHINESE互斥。
LCMAP_UPPERCASE 對於能夠處理大寫和小寫的地區設定和腳本,請將所有字元對應到大寫。

下列旗標可以單獨使用、彼此搭配使用,或搭配LCMAP_SORTKEY和/或LCMAP_BYTEREV旗標使用。 不過,它們無法與上面所列的其他旗標結合。

旗標 意義
NORM_IGNORENONSPACE
忽略非步調字元。 對於許多腳本, (特別是拉丁腳本) ,NORM_IGNORENONSPACE會與LINGUISTIC_IGNOREDIACRITIC一致。
注意 NORM_IGNORENONSPACE忽略任何次要區別,不論是否為讀音符號。 韓文、日文、中文和索引語言的腳本等等,會針對讀音符號以外的用途使用此區別。 LINGUISTIC_IGNOREDIACRITIC會導致函式只忽略實際的讀音符號,而不是忽略第二個排序權數。
 
NORM_IGNORESYMBOLS
忽略符號和標點符號。
 

以下所列的旗標只會與 LCMAP_SORTKEY 旗標搭配使用。

旗標 意義
LINGUISTIC_IGNORECASE
忽略大小寫,以語言方式適當。
LINGUISTIC_IGNOREDIACRITIC
請視語言適當地忽略非步調字元。
注意 當搭配分解字元使用時,這個旗標不一定會產生可預測的結果,也就是說,基底字元和一或多個非步調字元各有相異代碼點值的字元。
 
NORM_IGNORECASE
忽略大小寫。 對於許多腳本, (拉丁腳本) ,NORM_IGNORECASE會與LINGUISTIC_IGNORECASE一致。
注意 NORM_IGNORECASE會忽略任何第三個區別,不論其是否為語言案例。 例如,在阿拉伯文和索引腳本中,此旗標會區分字元的替代形式,但差異不會對應至語言案例。 LINGUISTIC_IGNORECASE會導致函式只忽略實際的語言大小寫,而不是忽略第三個排序權數。
 
注意 對於雙位元組字元集 (DBCS) 地區設定,NORM_IGNORECASE對所有 Unicode 字元以及窄 (一位元組) 字元的影響,包括希臘文和斯拉夫字元。
 
NORM_IGNOREKANATYPE
請勿區分平假名和片假名字符。 對應的平假名和片假名字符會比較為相等。
NORM_IGNOREWIDTH
忽略半角和全角字元之間的差異,例如 C a t == cat。 全角表單是中文和日文腳本中使用的格式區別。
NORM_LINGUISTIC_CASING
使用語言規則進行大小寫,而不是文件系統規則, (預設) 。
SORT_DIGITSASNUMBERS
Windows 7: 例如,在排序期間將數位視為數位,在 「10」 之前排序 「2」。。
SORT_STRINGSORT
將標點符號視為符號。

[in] lpSrcStr

函式對應或用於排序鍵產生的來源字串指標。 此字串的大小不能為 0。

[in] cchSrc

大小,以字元為單位,以字元為單位,以 lpSrcStr 表示的來源字串。 來源字串的大小可以包含終止的 Null 字元,但不需要。 如果包含終止的 Null 字元,函式的對應行為不會大幅影響,因為終止的 Null 字元會被視為不可排序,而且一律會對應至本身。

應用程式可以將此參數設定為任何負值,以指定來源字串為 Null 終止。 在此情況下,如果 LCMapStringEx 正用於其字串對應模式,則函式會計算字串長度本身,並以 Null 終止 lpDestStr 所指示的對應字串。

應用程式無法將此參數設定為 0。

[out, optional] lpDestStr

此函式擷取對應字串或排序索引鍵的緩衝區指標。

如果應用程式使用 函式來產生排序索引鍵 (LCMAP_SORTKEY) :

  • 排序索引鍵會儲存在緩衝區中,並視為不透明的位元組陣列。 預存值可以包含任何位置的內嵌 0 個字節。
  • 目的字串可以包含奇數位節。 LCMAP_BYTEREV旗標只會反轉偶數個字節。 排序索引鍵中最後一個字節 (奇數位置) 不會反轉。

如果呼叫端明確要求字串的子集,除非呼叫端在 cchDest 中指定字串,否則目的字串不會包含終止的 Null 字元。

如果此函式失敗,目的地緩衝區可能會包含部分結果或完全沒有結果。 在此情況下,所有結果都應該視為無效。

注意

設定LCMAP_UPPERCASE或LCMAP_LOWERCASE時,目的地字串可以使用與來源字元串相同的緩衝區。 不過,強烈建議您不要這樣做,因為某些條件可能會導致傳回的大小寫字串長度不同。

[in] cchDest

以字元為單位的大小,以字元為單位,以 lpDestStr 表示的目的地字串。 如果應用程式使用函式進行字串對應,則會提供此參數的字元計數。 如果終止 Null 字元的空間包含在 cchSrc 中, cchDest 也必須包含終止 Null 字元的空間。

如果應用程式使用函式來產生排序索引鍵,則會提供大小的位元組計數。 這個位元組計數必須包含排序索引鍵0x00終止符的空間。

應用程式可以將 cchDest 設定為 0。 在此情況下,函式不會使用 lpDestStr 參數,並傳回對應字串或排序索引鍵所需的緩衝區大小。

[in, optional] lpVersionInformation

NLSVERSIONINFOEX 結構的指標,其中包含相關 NLS 功能的版本資訊;通常從 GetNLSVersionEx 擷取。

Windows Vista、Windows 7: 保留;必須設定為 NULL。

[in, optional] lpReserved

保留;必須是 NULL。

[in, optional] sortHandle

保留;必須是 0。

注意

CompareStringExLCMapStringEx 可以在地區設定名稱為 null) 時指定排序句柄 (。 不建議對大部分的應用程式使用這項功能。

傳回值

如果函式用於字串對應時成功,它會傳回翻譯字串中的字元數, (請參閱 cchSrccchDest 以取得詳細數據) 。

如果函式用於產生排序索引鍵時成功,它會傳回排序索引鍵中的位元組數目。

如果函式不成功,此函式會傳回 0。 若要取得擴充的錯誤資訊,應用程式可以呼叫 GetLastError,這可以傳回下列其中一個錯誤碼:

  • ERROR_INSUFFICIENT_BUFFER。 提供的緩衝區大小不夠大,或設定為 NULL 不正確。
  • ERROR_INVALID_FLAGS。 為旗標的值無效。
  • ERROR_INVALID_PARAMETER。 任何參數值都無效。

備註

應用程式可以使用 LCMapStringLCMapStringEx 來產生排序索引鍵。 若要這樣做,應用程式會指定 dwMapFlags 參數LCMAP_SORTKEY。 如需詳細資訊,請參閱 處理應用程式中的排序

注意

排序索引鍵不透明位元組數據流。 呼叫端應該將它們視為 API 所傳回之長度的位元組陣列,而不依賴可能出現的任何內部結構。 零,傳回排序索引鍵中的一或多個字節可以是0。 不應該預期不存在或存在零位元組。

讓應用程式使用 LCMapStringLCMapStringEx 的另一種方式是在對應字串中。 在此情況下,應用程式不會為 dwMapFlags 參數指定LCMAP_SORTKEY,但會提供一些其他旗標組合。 如需詳細資訊,請參閱 處理應用程式中的排序

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

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

規格需求

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

另請參閱

CompareString

FindNLSStringEx

GetNLSVersionEx

處理應用程式中的排序

LCMapString

國家語言支援

國家語言支援函式