%>
将字符串的首个 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> |
有关兼容性的详细信息,请参阅 兼容性。