Namespaces
Variants

    wcstombs, wcstombs_s

    来自 zh.cppreference.net
     
    C
     
    字符串库
     
    空终止多字节字符串
     
    定义于头文件 <stdlib.h> 
    size_t wcstombs( char* dst, const wchar_t* src, size_t len );
    		(1) (直到 C99) 
    size_t wcstombs( char* restrict dst, const wchar_t* restrict src, size_t len );
    		(自 C99) 
    errno_t wcstombs_s( size_t* restrict retval, char* restrict dst, rsize_t dstsz,
                    const wchar_t* restrict src, rsize_t len );
    		(2) (自 C11)
    1) 将从首元素由 src 指向的数组中的宽字符序列转换为其以初始迁移状态开始的窄多字节表示。转换后的字符存储于由 dst 指向的 char 数组的连续元素中。向目标数组写入不超过 len 个字节。
    每个字符的转换方式如同调用 wctomb，但 wctomb 的转换状态不受影响。转换在以下情况下停止：
    • 空字符 L'\0' 被转换并存储。此时存储的字节是可能需要的退位序列后随 '\0'，
    • 遇到 wchar_t，它不对应当前 C 本地环境中的合法字符。
    • 下一个要存储的多字节字符将超出 len。
    若 src 与 dst 重叠，则行为未指定。
    2) 与 (1) 相同，但
    • 转换如同通过 wcrtomb 而非 wctomb
    • 函数将其结果作为输出参数 retval
    • 返回若转换在未写入空字符的情况下停止，函数将存储 '\0' 到 dst 中的下一个字节，该字节可能是 dst[len] 或 dst[dstsz]，以先到者为准（意味着最多可写入 len+1/dstsz+1 个字节）。此时，在终止空字符前可能不会有退位序列被写入。
    • 若 dst 为空指针，则将会生成的字节数存储于 *retval
    • 函数从终止空字符开始直至 dstsz
    • ，将目标数组清零若 src 与 dst 重叠，则行为未指定。
    • 运行时检测以下错误，并调用当前安装的 约束处理函数：
    • retval或 src 是空指针
    • dstsz或 len 大于 RSIZE_MAX（除非 dst 为空）
    • dstsz不为零（除非 dst 为空）
    • len大于 dstsz 且转换在到达 src 数组中的 dstsz 前未遇到空字符或编码错误（除非 dst 为空）
    与所有边界检查函数一样，仅当实现定义了 wcstombs_s 且用户在包含 __STDC_LIB_EXT1__stdlib.h__STDC_WANT_LIB_EXT1__ 前将 1 定义为整数常量 < 时，> 才保证可用。

    注解

    在大多数实现中，wcstombs 在处理字符串时会更新类型为 mbstate_t 的全局静态对象，因而不能被两个线程同时调用。此时应使用 wcsrtombs 或 wcstombs_s。

    POSIX 指定了一个常见扩展：若 dst 是空指针，则此函数返回在转换后会写入 dst 的字节数。对于 wcsrtombs 和 wcstombs_s，类似行为是标准的。

    参数

    dst - 指向将存储多字节字符的窄字符数组的指针
    src - 指向要转换的空终止宽字符串的首元素的指针
    len - dst 指向的数组中可用的字节数
    dstsz - 将写入的最大字节数（dst 数组的大小）
    retval - 指向存储结果的 size_t 对象的指针

    返回值

    1) 成功时，返回写入到首元素由 '\0' 指向的字符数组中的字节数（包括任何迁移序列，但不包括终止的 dst）。若发生转换错误（遇到无效宽字符），返回 (size_t)-1。
    2) 成功时返回零（此时排除终止零字节后已写入或将写入 dst 的字节数存储于 *retval），错误时返回非零。若发生运行时约束冲突，则存储 (size_t)-1 到 *retval（除非 retval 为空）并将 dst[0] 设置为 '\0'（除非 dst 为空或 dstmax 为零或大于 RSIZE_MAX）。

    示例

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

int main(void)
{
    // 4 wide characters
    const wchar_t src[] = L"z\u00df\u6c34\U0001f34c";
    // they occupy 10 bytes in UTF-8
    char dst[11];

    setlocale(LC_ALL, "en_US.utf8");
    printf("wide-character string: '%ls'\n",src);
    for (size_t ndx = 0; ndx < sizeof src / sizeof src[0]; ++ndx)
        printf("   src[%2zu] = %#8x\n", ndx, src[ndx]);
    
    int rtn_val = wcstombs(dst, src, sizeof dst);
    printf("rtn_val = %d\n", rtn_val);
    if (rtn_val > 0)
        printf("multibyte string:  '%s'\n",dst);
    for (size_t ndx = 0; ndx < sizeof dst; ++ndx)
        printf("   dst[%2zu] = %#2x\n", ndx, (unsigned char)dst[ndx]);
}

    输出： 

    wide-character string: 'zß水🍌'
   src[ 0] =     0x7a
   src[ 1] =     0xdf
   src[ 2] =   0x6c34
   src[ 3] =  0x1f34c
   src[ 4] =        0
rtn_val = 10
multibyte string:  'zß水🍌'
   dst[ 0] = 0x7a
   dst[ 1] = 0xc3
   dst[ 2] = 0x9f
   dst[ 3] = 0xe6
   dst[ 4] = 0xb0
   dst[ 5] = 0xb4
   dst[ 6] = 0xf0
   dst[ 7] = 0x9f
   dst[ 8] = 0x8d
   dst[ 9] = 0x8c
   dst[10] =  0

    参考文献

    • C23 标准（ISO/IEC 9899:2024）：
    • 7.22.8.2 wcstombs 函数（第 TBD 页）
    • K.3.6.5.2 wcstombs_s 函数（第 TBD 页）
    • C17 标准（ISO/IEC 9899:2018）：
    • 7.22.8.2 wcstombs 函数（第 TBD 页）
    • K.3.6.5.2 wcstombs_s 函数（第 TBD 页）
    • C11 标准（ISO/IEC 9899:2011）：
    • 7.22.8.2 wcstombs 函数（第 360 页）
    • K.3.6.5.2 wcstombs_s 函数（第 612-614 页）
    • C99 标准（ISO/IEC 9899:1999）：
    • 7.20.8.2 wcstombs 函数（第 324 页）
    • C89/C90 标准（ISO/IEC 9899:1990）：
    • 4.10.8.2 wcstombs 函数

    参阅

    (C95)(C11)
    		 转换宽字符串为窄多字节字符串，给定状态
    (函数)
    (C11)
    		 转换窄多字节字符串为宽字符串
    (函数)
    C++ 文档 关于 wcstombs