c16rtomb

将单个码点从其可变长度16位宽字符表示（通常为UTF-16）转换为其窄多字节字符表示。

如果 s 不是空指针且 c16 是某个代码点有效变长编码中的最后一个16位代码单元，该函数将确定存储该代码点多字节字符表示所需的字节数（包括任何移位序列，并考虑当前多字节转换状态 * ps ），并将多字节字符表示存储到由 s 指向首元素的字符数组中，同时根据需要更新 * ps 。此函数最多可写入 MB_CUR_MAX 字节。

如果 s 是空指针，该调用等价于对某个内部缓冲区 buf 执行 c16rtomb ( buf, u ' \0 ' , ps ) 。

如果 c16 是空宽字符 u ' \0 ' ，将存储一个空字节，并在其前插入恢复初始移位状态所需的任何移位序列，同时转换状态参数 * ps 将被更新以表示初始移位状态。

如果 c16 不是宽字符16位表示中的最终代码单元，则不会写入由 s 指向的数组，仅更新 * ps 。

若宏 __STDC_UTF_16__ 被定义，则此函数使用的16位编码为UTF-16；否则由实现定义。 该宏始终被定义且编码始终为UTF-16。 (C23起) 无论何种情况，此函数使用的多字节字符编码由当前生效的C区域设置指定。

参数

返回值

成功时，返回写入到以 s 指向的首元素的字符数组的字节数（包括任何移位序列）。该值可能为 ​ 0 ​ ，例如在处理多 char16_t 单元序列中的前导 char16_t 单元时（发生在处理 UTF-16 代理对中的前导代理项时）。

当失败时（如果 c16 不是有效的16位码元），返回 - 1 ，将 EILSEQ 存入 errno ，并使 * ps 处于未指定状态。

注释

在已发布的C11标准中，与可将变宽多字节（如UTF-8）编码转换为变宽16位（如UTF-16）编码的 mbrtoc16 不同，此函数仅能转换单单元16位编码，这意味着尽管该函数的设计初衷是实现UTF-16到UTF-8的转换，但实际上无法完成该转换。此问题已通过C11发布后的缺陷报告 DR488 得到修正。

示例

#include <locale.h>
#include <stdio.h>
#include <stdlib.h>
#include <uchar.h>
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    const char16_t in[] = u"zß水🍌"; // or "z\u00df\u6c34\U0001F34C"
    const size_t in_sz = sizeof in / sizeof *in;
    printf("Processing %zu UTF-16 code units: [", in_sz);
    for (size_t n = 0; n < in_sz; ++n)
        printf("%s%04X", n ? " " : "", in[n]);
    puts("]");
    char* out = malloc(MB_CUR_MAX * in_sz);
    char* p = out;
    mbstate_t state = {0};
    for (size_t n = 0; n < in_sz; ++n)
    {
        size_t rc = c16rtomb(p, in[n], &state);
        if (rc == (size_t)-1)
            break;
        p += rc;
    }
    size_t out_sz = p - out;
    printf("into %zu UTF-8 code units: [", out_sz);
    for (size_t x = 0; x < out_sz; ++x)
        printf("%s%02X", x ? " " : "", +(unsigned char)out[x]);
    puts("]");
    free(out);
}

Processing 6 UTF-16 code units: [007A 00DF 6C34 D83C DF4C 0000]
into 13 UTF-8 code units: [7A C3 9F E6 B0 B4 ED A0 BC ED BD 8C 00]

参考文献

参见