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) 後續對 CompareStringEx 或 LCMapStringEx 的呼叫。

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。

注意

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

傳回值

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

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

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

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

備註

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

注意

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

讓應用程式使用 LCMapString 或 LCMapStringEx 的另一種方式是在對應字串中。 在此情況下，應用程式不會為 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

國家語言支援

國家語言支援函式