Namespaces
Variants

    wcrtomb, wcrtomb_s

    来自 zh.cppreference.net
     
    C
     
    字符串库
     
    空终止多字节字符串
     
    定义于头文件 <wchar.h> 
    size_t wcrtomb( char* s, wchar_t wc, mbstate_t* ps);
    		(1) （自 C95 起）
    （直到 C99）    		 
    size_t wcrtomb( char* restrict s, wchar_t wc, mbstate_t* restrict ps);
    		（自 C99 起） 
    errno_t wcrtomb_s(size_t* restrict retval, char* restrict s, rsize_t ssz,
                  wchar_t wc, mbstate_t* restrict ps);
    		(2) （自 C11 起）

    将宽字符转换为其窄多字节表示。

    1) 如果 s 不是空指针，则该函数确定存储 wc 的多字节字符表示（包括任何移位序列，并考虑当前多字节转换状态 *ps）所需的字节数，并将多字节字符表示存储在首元素由 s 指向的字符数组中，并按需更新 *ps。此函数最多可写入 MB_CUR_MAX 个字节。
    如果 s 是空指针，则该调用等价于 wcrtomb(buf, L'\0', ps)，且内部缓冲为 buf。
    如果 wc 是空宽字符 L'\0'，则存储一个空字节，并在其前面加上恢复初始移位状态所需的任何移位序列，并将转换状态参数 *ps 更新为表示初始移位状态。
    如果定义了环境宏 __STDC_ISO_10646__，则类型 wchar_t 的值与 Unicode 必需集中字符的短标识符相同（通常为 UTF-32 编码）；否则由实现定义。在任何情况下，此函数使用的多字节字符编码由当前激活的 C 语言环境指定。
    2) 与 (1) 相同，不同之处在于：
    如果 s 是空指针，则该调用等价于 wcrtomb_s(&retval, buf, sizeof buf, L'\0', ps)，使用内部变量 retval 和 buf（其大小大于 MB_CUR_MAX）
    结果通过输出参数 retval
    以下错误在运行时检测并调用当前安装的 约束处理 函数：
    • retval 或 ps 是空指针。
    • ssz 为零或大于 RSIZE_MAX（除非 s 为空）
    • ssz 小于将写入的字节数（除非 s 为空）
    • s 是空指针但 ssz 非零
    与所有边界检查函数一样，wcrtomb_s 仅在以下情况下保证可用：如果 __STDC_LIB_EXT1__ 由实现定义且用户定义了 __STDC_WANT_LIB_EXT1__ 为整数常量 1 在包含 <wchar.h>。

    参数

    s - 指向窄字符数组的指针，多字节字符将存储在其中
    wc - 要转换的宽字符
    ps - 指向转换状态对象的指针，用于解释多字节字符串
    ssz - 要写入的最大字节数（缓冲区 s 的大小）
    retval - 指向输出参数的指针，用于存储结果（多字节字符串中的字节数，包括任何移位序列）

    返回值

    1) 成功时，返回写入到首元素由 s 指向的字符数组的字节数（包括任何移位序列）。
    失败时（如果 wc 不是有效的宽字符），返回 (size_t)-1，存储 EILSEQ 于 errno，并将 *ps 置于未指定状态。
    2) 成功时返回零，失败时返回非零，此时 s[0] 被设置为 '\0'（除非 s 为空或 ssz 为零或大于 RSIZE_MAX），且 *retval 被设置为 (size_t)-1（除非 retval 为空）

    示例

    运行此代码
    #include <locale.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <wchar.h>

int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    mbstate_t state;
    memset(&state, 0, sizeof state);
    wchar_t in[] = L"zß水🍌"; // or "z\u00df\u6c34\U0001F34C"
    size_t in_sz = sizeof in / sizeof *in;
 
    printf("Processing %zu wchar_t units: [ ", in_sz);
    for (size_t n = 0; n < in_sz; ++n)
        printf("%#x ", (unsigned int)in[n]);
    puts("]");
 
    char out[MB_CUR_MAX * in_sz];
    char* p = out;
    for (size_t n = 0; n < in_sz; ++n)
    {
        int rc = wcrtomb(p, in[n], &state);
        if (rc == -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("%#x ", +(unsigned char)out[x]);
    puts("]");
}

    输出： 

    Processing 5 wchar_t units: [ 0x7a 0xdf 0x6c34 0x1f34c 0 ]
into 11 UTF-8 code units: [ 0x7a 0xc3 0x9f 0xe6 0xb0 0xb4 0xf0 0x9f 0x8d 0x8c 0 ]

    引用

    • C23 标准（ISO/IEC 9899:2024）：
    • 7.29.6.3.3 wcrtomb 函数（第 TBD 页）
    • K.3.9.3.1.1 wcrtomb_s 函数（第 TBD 页）
    • C17 标准（ISO/IEC 9899:2018）：
    • 7.29.6.3.3 wcrtomb 函数（第 TBD 页）
    • K.3.9.3.1.1 wcrtomb_s 函数（第 TBD 页）
    • C11 标准（ISO/IEC 9899:2011）：
    • 7.29.6.3.3 wcrtomb 函数（第 444 页）
    • K.3.9.3.1.1 wcrtomb_s 函数（第 647-648 页）
    • C99 标准（ISO/IEC 9899:1999）：
    • 7.24.6.3.3 wcrtomb 函数（第 390 页）

    参阅

    (C11)
    		 将宽字符转换为其多字节表示
    （函数）
    (C95)
    		 将下一个多字节字符转换为宽字符，给定状态
    （函数）
    C++ 文档 的 wcrtomb