foldStringW 函数 (stringapiset.h)

将一个 Unicode 字符串映射到另一个,执行指定的转换。 有关字符串函数用法的概述,请参阅 字符串

谨慎 错误地使用 FoldString 可能会危及应用程序的安全性。 未正确映射的字符串可能会产生无效的输入。 测试字符串,确保它们在使用前有效,并提供错误处理程序。 有关详细信息,请参阅 安全注意事项:国际功能
 

语法

int FoldStringW(
  [in]            DWORD                         dwMapFlags,
  [in]            _In_NLS_string_(cchSrc)LPCWCH lpSrcStr,
  [in]            int                           cchSrc,
  [out, optional] LPWSTR                        lpDestStr,
  [in]            int                           cchDest
);

参数

[in] dwMapFlags

指定要在字符串映射期间使用的转换类型的标志。 此参数可以是以下值的组合。

标志 含义
MAP_COMPOSITE
将重音字符映射到分解字符,即基字符和一个或多个非节奏字符各自具有不同的码位值的字符。 例如,Ä 由 A + ー:拉丁文大写字母 A (U+0041) + 组合分音 (U+0308) 。 此标志等效于 Windows Vista 中的规范化形式 D。 请注意,此标志不能与MB_PRECOMPOSED一起使用。
MAP_EXPAND_LIGATURES
展开所有连字字符,使其由两个字符等效表示。 例如,连字“æ” (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 指示的目标字符串的大小(以字符为单位)。 如果 cchSrc 中包含终止 null 字符的空间, 则 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。 找不到所需的过程。

注解

lpSrcStrlpDestStr 参数的值不能相同。 如果它们相同,则函数将失败并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 Professional [仅限桌面应用]
最低受支持的服务器 Windows 2000 Server [仅限桌面应用]
目标平台 Windows
标头 stringapiset.h (包括 Windows.h)
Library Kernel32.lib
DLL Kernel32.dll

另请参阅

国家/地区语言支持

国家/地区语言支持函数

NormalizeString

安全注意事项:国际功能

排序

使用 Unicode 规范化来表示字符串