%>
将字符串的首个 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++ 标头 |
|---|---|---|
| %> | <uchar.h> | <cuchar> |
有关兼容性的详细信息，请参阅 兼容性。