wcstombs, wcstombs_s

来自cppreference.com
 
C
 
字符串库
 
空终止多字节字符串
 
在标头 <stdlib.h> 定义
(1) 
size_t wcstombs( char          *dst, const wchar_t          *src, size_t len );
(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 所指向的数组的相继元素。写入目标数组的字节数不多于 len。
如同以调用 wctomb 来转换每个字符，但 wctomb 的转换状态不受影响。若满足下列条件则转换停止：
* 转换并存储空字符 L'\0'。此情况下存储的各字节为无迁移序列（若需要）后随 '\0'，
* 找到当前 C 本地环境中不对应合法字符的 wchar_t。
* 下个要存储的多字节字符会超出 len。
若 src 与 dst 重叠，则行为未指定。
2) 同 (1)，但
* 转换如同以 wcrtomb 而非 wctomb 进行
* 函数将其结果作为输出参数 retval 返回
* 若转换停止而不写入控制符，则函数将在 dst 中的下个字符，可以是 dst[len] 或 dst[dstsz] 的先到来者，存储 '\0'（表示可能写入总计至多 len+1/dsz+1 个字符）。该情况下，空终止前不写入无迁移序列。
* 若 dst 是空指针，则将本会产生的字节数存储于 *retval
* 函数从空终止起到 dstsz 前为止破坏目标数组
* 若 src 与 dst 重叠，则行为未指定。
* 在运行时检测下列错误，并调用当前安装的约束处理函数：
  • retval 或 src 是空指针
  • dstsz 或 len 大于 RSIZE_MAX（除非 dst 为空）
  • dstsz 非零（除非 dst 为空）
  • len 大于 dstsz 且直到抵达 dstsz 时，转换未于 src 数组遇到空字符或编码错误（除非 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) 成功时，返回写入首元素为 dst 所指向的字符数组的字节数（包含任何迁移序列，但不含终止的 '\0'）。转换错误时（若遇到非法宽字符），返回 (size_t)-1。
2) 成功时返回零（该情况下，将被或本应写入 dst 的字节数，排除终止零，存储于 *retval），错误时返回非零。运行时制约违规的情况下，存储 (size_t)-1 于 *retval（除非 retval 为空）并设置 dst[0] 为 '\0'（除非 dst 为空或 dstmax 为零或大于 RSIZE_MAX）。

示例

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

int main(void)
{
    // 4 个宽字符
    const wchar_t src[] = L"z\u00df\u6c34\U0001f34c";
    // 它们于 UTF-8 占用 10 个字节
    char dst[11];

    setlocale(LC_ALL, "en_US.utf8");
    printf("宽字符字符串：'%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("多字节字符串：'%s'\n", dst);
    for (size_t ndx=0; ndx<sizeof dst; ++ndx)
        printf("   dst[%2zu] = %#2x\n", ndx, (unsigned char)dst[ndx]);
}

输出： 

宽字符字符串：'zß水🍌'
   src[ 0] =     0x7a
   src[ 1] =     0xdf
   src[ 2] =   0x6c34
   src[ 3] =  0x1f34c
   src[ 4] =        0
rtn_val = 10
多字节字符串：'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

引用

  • C11 标准（ISO/IEC 9899:2011）：
  • 7.22.8.2 The wcstombs function （第 360 页）
  • K.3.6.5.2 The wcstombs_s function （第 612-614 页）
  • C99 标准（ISO/IEC 9899:1999）：
  • 7.20.8.2 The wcstombs function （第 324 页）
  • C89/C90 标准（ISO/IEC 9899:1990）：
  • 4.10.8.2 The wcstombs function

参阅

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