wcstombs, wcstombs_s

定义于头文件 `<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 wide characters
    const wchar_t src[] = L"z\u00df\u6c34\U0001f34c";
    // 它们于 UTF-8 占用 10 个字节
    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

引用

C11 standard (ISO/IEC 9899:2011):

7.22.8.2 The wcstombs function (p: 360)

K.3.6.5.2 The wcstombs_s function (p: 612-614)

C99 standard (ISO/IEC 9899:1999):

7.20.8.2 The wcstombs function (p: 324)

C89/C90 standard (ISO/IEC 9899:1990):

4.10.8.2 The wcstombs function

参阅

wcsrtombswcsrtombs_s (C95)(C11)	给定状态，将宽字符串转换成窄多字节字符串 (函数)
mbstowcsmbstowcs_s (C11)	将窄多字节字符串转换成宽字符串 (函数)

语言
头文件
类型支持
程序工具
变参数函数支持
动态内存管理
错误处理
日期和时间工具
字符串库
算法
数值
输入/输出支持
本地化支持
线程支持 (C11)
原子操作 (C11)
技术规范

wcstombs, wcstombs_s

注意

参数

返回值

示例

引用

参阅

导航