c32rtomb

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

如果 s 不是空指针，该函数将确定存储 c32 的多字节字符表示形式所需的字节数（包括任何移位序列，并考虑当前多字节转换状态 * ps ），并将多字节字符表示形式存储在以 s 指向的首元素的字符数组中，同时根据需要更新 * ps 。此函数最多可写入 MB_CUR_MAX 字节。

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

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

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

参数

返回值

成功时，返回写入到以 s 指向的首元素的字符数组的字节数（包括任何移位序列）。该值可能为 ​ 0 ​ ，例如在处理多 char32_t 单元序列中的前导 char32_t 单元时（在UTF-32编码中不会出现这种情况）。

当失败时（如果 c32 不是有效的32位宽字符），返回 - 1 ，将 EILSEQ 存入 errno ，并使 * ps 保持未指定状态。

示例

#include <locale.h>
#include <stdio.h>
#include <stdlib.h>
#include <uchar.h>
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    const char32_t in[] = U"zß水🍌"; // or "z\u00df\u6c34\U0001F34C"
    size_t in_sz = sizeof in / sizeof *in;
    printf("Processing %zu UTF-32 code units: [", in_sz);
    for (size_t n = 0; n < in_sz; ++n)
        printf("%s%08X", 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 = c32rtomb(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 5 UTF-32 code units: [0000007A 000000DF 00006C34 0001F34C 00000000]
into 11 UTF-8 code units: [7A C3 9F E6 B0 B4 F0 9F 8D 8C 00]

参考文献

参见