mbrtoc16，mbrtoc32

将字符串的首个 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_t 或 char32_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，这些函数会返回使用destination的NULL参数、source的""（以 null 结尾的空字符串）和max_bytes的 1 进行调用的等效项。 传递的值 destination 和 max_bytes 将被忽略。

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

若要将非 UTF-8 多字节字符转换为 UTF-16 LE 字符，请使用 mbrtowc、mbtowc_mbtowc_l函数。

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

要求

函数	C 标头	C++ 标头
mbrtoc16，mbrtoc32	<uchar.h>	<cuchar>

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

另请参阅

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