wcrtomb, wcrtomb_s

在标头 `<wchar.h>` 定义
	(1)
size_t wcrtomb( char s, wchar_t wc, mbstate_t ps);			(C95 起)
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 为空指针，则调用等价于对某内部缓冲区 buf 的 wcrtomb(buf, L'\0', ps)。

若 wc 是空宽字符 L'\0'，则存储空字节，前接恢复到初始迁移状态所需的任何迁移序列，并更新转换状态参数 *ps 以表示其初始迁移状态。

若定义了环境宏 __STDC_ISO_10646__，则 wchar_t 类型的值与 Unicode 必要集合（典型地为 UTF-32 编码）中字符的短标识符相同；否则它是实现定义的。任何情况下，此函数所用的多字节字符编码为当前活跃的 C 本地环境所指定。

2) 同 (1)，但

若 s 为空指针，则调用等价于使用内部变量 retval 和 buf（其大小大于 MB_CUR_MAX）的 wcrtomb_s(&retval, buf, sizeof buf, L'\0', ps)

其结果在输出参数 retval 中返回

在运行时检测下列错误，并调用当前安装的约束处理函数：

retval 或 ps 为空指针。
ssz 为零或大于 RSIZE_MAX（除非 s 为空）
ssz 小于会写入的字节数（除非 s 为空）
s 为空指针但 ssz 非零

同所有边界检查函数，wcrtomb_s，仅若实现定义 __STDC_LIB_EXT1__ 且用户在包含 <wchar.h> 前定义 __STDC_WANT_LIB_EXT1__ 为整数常量 1 才保证可用。

参数

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 <stdio.h>
#include <locale.h>
#include <string.h>
#include <wchar.h>
#include <stdlib.h>
 
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    mbstate_t state;
    memset(&state, 0, sizeof state);
    wchar_t in[] = L"zß水🍌"; // 或 "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 ]

引用

C11 标准（ISO/IEC 9899:2011）：

7.29.6.3.3 The wcrtomb function （第 444 页）

K.3.9.3.1.1 The wcrtomb_s function （第 647-648 页）

C99 标准（ISO/IEC 9899:1999）：

7.24.6.3.3 The wcrtomb function （第 390 页）

参阅

wctombwctomb_s (C11)	将宽字符转换成其多字节表示 (函数)
mbrtowc (C95)	给定状态，将下一个多字节字符转换成宽字符 (函数)

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

wcrtomb, wcrtomb_s

参数

返回值

示例

引用

参阅

导航