std::mbrtoc8

< cpp‎ | string‎ | multibyte
定义于头文件 <cuchar>
std::size_t mbrtoc8( char8_t* pc8,

                     const char* s,
                     std::size_t n,

                     std::mbstate_t* ps );
(C++20 起)

转换窄多字节字符为 UTF-8 编码。

s 不是空指针,则审视始于 s 所指向字符的多字节字符串的至多 n 个字节,以确定完成下个多字节字符所需的字节数(包含任何迁移序列)。若函数确定 s 中的下个多字节字符完整且合法,则将它转换成 UTF-8 并存储首个 UTF-8 编码单元于 *pc8 (若 pc8 非空)。

*s 中的多字节字符的 UTF-8 编码由多于一个 UTF-8 编码单元组成,则在首次调用此函数后更新 *ps ,以使得下次调用 mbrtoc8 会写出另外的 UTF-8 编码单元,而不考虑 *s

s 为空指针,则忽略 npc8 的值,而调用等价于 std::mbrtoc8(NULL, "", 1, ps)

若产生的 UTF-8 编码单元为 u8'\0' ,则转换状态 *ps 代表初始迁移状态。

此函数所用的多字节编码由当前活跃的 C 本地环境指定。

参数

pc8 - 指向将写入生成的 UTF-8 编码单元的位置的指针
s - 指向用作输入的多字节字符串的指针
n - s 中能检验的字节数上的限制
ps - 指向转译多字节字符串时使用的转换状态对象的指针

返回值

下列的首个成立者:

  • 0 ,若从 s 转换(而若 pc8 非空则存储于 *pc8 )的字符是空字符。
  • [1...n] ,从 s 成功转换的多字节字符的字节数。
  • -3 ,若现在已将来自由多个编码单元组成的字符的下个 UTF-8 编码单元写入 *pc8 。此情况下不处理来自输入的字节。
  • -2 ,若下 n 个字节组成不完整但到此仍合法的多字节字符。不写入任何内容到 *pc8
  • -1 ,若编码错误出现。不写入任何内容到 *pc8 ,存储值 EILSEQerrno ,而 *ps 的值未指定。

示例

参阅

(C++20)
转换 UTF-8 字符串为窄多字节编码
(函数)