FoldStringA 函式 (winnls.h)

發行項
03/13/2024

將一個 Unicode 字串對應到另一個 Unicode 字串，並執行指定的轉換。如需字串函式使用概觀，請參閱字串。

謹慎使用 FoldString 不正確可能會危害應用程式的安全性。未正確對應的字串會產生無效的輸入。測試字串，以確保它們在使用之前有效，並提供錯誤處理程式。如需詳細資訊，請參閱安全性考慮：國際功能。

語法

int FoldStringA(
  [in]            DWORD  dwMapFlags,
  [in]            LPCSTR lpSrcStr,
  [in]            int    cchSrc,
  [out, optional] LPSTR  lpDestStr,
  [in]            int    cchDest
);

參數

[in] dwMapFlags

旗標，指定要在字串對應期間使用的轉換類型。此參數可以是下列值的組合。

旗標	意義
MAP_COMPOSITE	將輔色字元對應至分解的字元，也就是基底字元和一或多個非步調字元各自具有相異字碼點值的字元。例如，Ä 是以 A + ー：拉丁大寫字母 A (U+0041) + 合併 DIAERESIS (U+0308) 。此旗標相當於 Windows Vista 中的正規化窗體 D。請注意，此旗標不能與 MB_PRECOMPOSED搭配使用。
MAP_EXPAND_LIGATURES	展開所有 Ligature 字元，使其以兩個字元對等的表示。例如，ligature “æ” (U+00e6) 會展開為兩個字元 “a” (U+0061) + “e” (U+0065) 。此值無法與MAP_PRECOMPOSED或MAP_COMPOSITE結合。
MAP_FOLDCZONE	將相容性區域字元折迭成標準 Unicode 對等專案。如果同時設定MAP_COMPOSITE旗標，此旗標相當於 Windows Vista 中的正規化表單 KD。如果未設定複合旗標 (預設) ，則此旗標相當於 Windows Vista 中的正規化表單 KC。
MAP_FOLDDIGITS	將所有數字對應至 Unicode 字元 0 到 9。
MAP_PRECOMPOSED	將輔色字元對應至預先編譯的字元，其中輔色和基底字元會合併成單一字元值。此旗標相當於 Windows Vista 中的正規化窗體 C。此值無法與MAP_COMPOSITE結合。

[in] lpSrcStr

函式所對應的來源字串指標。

[in] cchSrc

lpSrcStr 所表示來源字串的大小，以字元為單位，不包括終止的 Null 字元。應用程式可以將參數設定為任何負值，以指定來源字串為 Null 終止。在此情況下，函式會自動計算字串長度，並以 null 終止 lpDestStr 所指示的對應字串。

[out, optional] lpDestStr

這個函式擷取對應字串的緩衝區指標。

[in] cchDest

以字元為單位的目的地字串大小，以 lpDestStr 表示。如果終止 Null 字元的空間包含在 cchSrc 中， cchDest 也必須包含終止 Null 字元的空間。

應用程式可以將 cchDest 設定為 0。在此情況下，函式不會使用 lpDestStr 參數，並傳回對應字串所需的緩衝區大小。如果指定MAP_FOLDDIGITS旗標，則傳回值是所需的大小上限，即使所需的實際字元數小於大小上限也一樣。如果未傳遞大小上限，函式會失敗，並ERROR_INSUFFICIENT_BUFFER。

傳回值

如果成功，則會傳回翻譯字串中的字元數，包括終止 Null 字元。如果函式成功且 cchDest 的值是 0，則傳回值是保存已轉譯字串所需的緩衝區大小，包括終止的 Null 字元。

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

ERROR_INSUFFICIENT_BUFFER。提供的緩衝區大小不夠大，或設定為 NULL 不正確。
ERROR_INVALID_DATA。數據無效。
ERROR_INVALID_FLAGS。為旗標的值無效。
ERROR_INVALID_PARAMETER。任何參數值都無效。
ERROR_MOD_NOT_FOUND。找不到模組。
ERROR_OUTOFMEMORY。沒有足夠的記憶體可完成這項作業。
ERROR_PROC_NOT_FOUND。找不到必要的程式。

備註

lpSrcStr 和 lpDestStr 參數的值不得相同。如果相同，函式會失敗，並ERROR_INVALID_PARAMETER。

Unicode 中的相容性區域是由範圍中的字元所組成，0xF900到指派給字元的其他編碼標準字元 0xFFEF，但實際上是 Unicode 中字元的變異。相容性區域是用來支持這些標準的來回對應。應用程式可以使用 MAP_FOLDCZONE 旗標，以避免支援相容性區域中的字元重複。

從 Windows Vista 開始： 此函式支援 Unicode 正規化。所有 Unicode 相容性字元都會對應。

從 Windows Vista 開始： MAP_FOLDCZONE、MAP_PRECOMPOSED和MAP_COMPOSITE旗標所指示的轉換會透過 NormalizeString 函式使用 Unicode 正規化表單 KC、C 和 D) (來執行對應。

從 Windows 8 開始：函式的 ANSI 版本是在 Winnls.h 中宣告，而 Unicode 版本是在 Stringapiset.h 中宣告。在 Windows 8 之前，這兩個版本都是在 Winnls.h 中宣告的。

規格需求

需求	值
最低支援的用戶端	Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	winnls.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll