%>

将字符串的首个 UTF-8 多字节字符转换为等效的 UTF-16 或 UTF-32 字符。

语法

size_t mbrtoc16(
   char16_t* destination,
   const char* source,
   size_t max_bytes,
   mbstate_t* state
);

size_t mbrtoc32(
   char32_t* destination,
   const char* source,
   size_t max_bytes,
   mbstate_t* state
);

参数

destination
指向与要转换的 UTF-8 多字节字符等效的 char16_tchar32_t 的指针。 如果为 null,则该函数不存储值。

source
指向要转换的 UTF-8 多字节字符串的指针。

max_bytes
存储在 source 中用于测试转换字符的最大字节数。 此参数应是介于 1 到source中的剩余字节数之间的值(包括任何 null 终止符)。

state
指向用于将 UTF-8 多字节字符串解释为一个或多个输出字符的mbstate_t转换状态对象。

返回值

如果成功,返回第一个适用条件的值,假定当前 state 值为:

条件
0 下一个从max_bytes转换的source或者较少字符与 null 宽字符对应,该字符是destination不为 null 时存储的值。

state 包含初始位移状态。
介于 1 和 max_bytes之间(包括这两个值) 返回的值是填充有效多字节字符的 source 的字节数。 如果destination不为 null,会存储转换后的宽字符。
-3 如果destination不为 null,则通过上次函数调用生成的下一个宽字符存储在destination中。 此次函数调用不会使用 source 中的字节。

source指向需要用多个宽字符表示的 UTF-8 多字节字符(例如代理项对)时,会更新state值,以便下一个函数调用写出额外字符。
-2 下一个max_bytes字节表示不完整但可能有效的 UTF-8 多字节字符。 destination中不存储任何值。 如果 max_bytes 为 0,会出现此结果。
-1 发生编码错误。 下一个max_bytes或更少字节数不有利于实现完整且有效的 UTF-8 多字节字符。 destination中不存储任何值。

EILSEQ存储在errno中,未指定转化状态值state

注解

mbrtoc16函数最多可从max_bytes中读取source个字节,以查找第一个完整有效的 UTF-8 多字节字符,然后将等效的 UTF-16 字符存储在destination中。 如果字符需要多个 UTF 16 输出字符,如代理项对,则state值被设置为在下一次调用destination时将下一个 UTF-16 字符存储在mbrtoc16中。 mbrtoc32 函数完全相同,但输出存储为 UTF-32 字符。

如果source为 null,这些函数会返回使用destinationNULL参数、source""(以 null 结尾的空字符串)和max_bytes的 1 进行调用的等效项。 传递的值 destinationmax_bytes 将被忽略。

如果source不为 null,函数从字符串起始位置开始,最多检查max_bytes个字节,以确定填充下一个 UTF-8 多字节字符(包括任何位移序列)所需的字节数。 如果检查的字节包含有效且完整的 UTF-8 多字节字符,该函数将字符转换为等效的 16 位或 32 位宽字符或字符。 如果destination不为 null,该函数会在目标中存储第一个(并且可能是唯一的)结果字符。 如果需要额外的输出字符,会在state中设置值,以便对函数的后续调用输出额外字符并返回值 -3。 如果不需要其他输出字符,则将 state 设置为初始位移状态。

若要将非 UTF-8 多字节字符转换为 UTF-16 LE 字符,请使用 mbrtowcmbtowc_mbtowc_l函数。

默认情况下,此函数的全局状态范围限定为应用程序。 若要更改此行为,请参阅 CRT 中的全局状态

要求

函数 C 标头 C++ 标头
%> <uchar.h> <cuchar>

有关兼容性的详细信息,请参阅 兼容性

另请参阅

数据转换
区域设置
多字节字符序列的解释
%>
mbrtowc
mbsrtowcs
mbsrtowcs_s