wctomb, wctomb_s

 

C

编译器支持

语言

头文件

类型支持

程序工具

变参数函数支持

错误处理

动态内存管理

字符串库

算法

数值

日期和时间工具

输入/输出支持

本地化支持

并发支持 (C11)

技术规范

符号索引

 

字符串库

字节字符串

多字节字符串

宽字符串

 

空终止多字节字符串

宽/多字节转换
mbsinit (C95)
mbstowcsmbstowcs_s (C11) btowc (C95) mbrtowc (C95) mbsrtowcsmbsrtowcs_s (C95)(C11)     mbrtoc8 (C23) c8rtomb (C23) mbrtoc16 (C11) c16rtomb (C11) c32rtomb (C11) mbrtoc32 (C11)	mblen mbtowc wctombwctomb_s (C11) wcstombswcstombs_s (C11) wctob (C95) wcrtombwcrtomb_s (C95)(C11) wcsrtombswcsrtombs_s (C95)(C11) mbrlen (C95)
类型
mbstate_t (C95)

 

在标头 <stdlib.h> 定义
int wctomb( char *s, wchar_t wc );	(1)
errno_t wctomb_s(int *restrict status, char *restrict s, rsize_t ssz, wchar_t wc);	(2)	(C11 起)

1) 转换宽字符 wc 为多字节编码，并将之（含迁移状态）存储于 s 指向其首元素的字符数组。存储字节数不多于 MB_CUR_MAX。转换受到当前安装的本地环境的 LC_CTYPE 类别的影响。

若 wc 是空字符，则将空字符写入 s，之前可以有需要恢复初始迁移状态的任何迁移状态。

若 s 是空指针，则此函数重设全局转换状态并确定是否使用迁移序列。

2) 同 (1)，除了结果被返回到输出参数 status，在运行时检测下列错误，并调用当前安装的约束处理函数：

• ssz 小于会被写入的字节数（除非 s 为空）
• ssz 大于 RSIZE_MAX（除非 s 为空）
• s 为空指针但 ssz 非零

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

注意

每次对 wctomb 的调用会更新全局转换状态（mbstate_t 类型的静态对象，只为此函数所知）。若多字节编码使用迁移状态，则此函数不可重入。任何情况下，多个线程不应调用 wctomb 而不同步：可使用 wcrtomb 或 wctomb_s 代替。

不同于大多数边界检查函数，wctomb_s 不以空字符终止其输出，因为它被设计以用于逐字节处理的循环。

参数

s	-	指向输出用字符数组的指针
wc	-	要转换的宽字符
ssz	-	要写入 s 的最大字节数（数组 s 的大小）
status	-	指向结果（多字节序列长度或迁移序列状态）存储位置的输出参数的指针

返回值

1) 若 s 非空指针，则返回 wc 的多字节表示所含的字节数，或者若 wc 非合法字符则为 -1。

若 s 是空指针，则重设内部转换状态以表示初始迁移状态，并若当前多字节编码非状态依赖（不使用迁移序列）则返回 ​0​，或者若当前多字节编码为状态依赖（使用迁移序列）则返回非零值。

2) 成功时为零，此情况下存储 wc 的多字节表示于 s，并存储其长度于 *status，或若 s 为空，则存储迁移序列状态于 *status。编码错误或运行时制约错误发生时为非零，此情况下存储 (size_t)-1 于 *status。存储于 *status 的值决不超过 MB_CUR_MAX。

示例

运行此代码

#include <stdio.h>
#include <stdlib.h>
#include <locale.h>
 
void demo(wchar_t wc)
{
    const char* dep = wctomb(NULL, wc) ? "Yes" : "No";
    printf("State-dependent encoding? %s.\n", dep);
 
    char mb[MB_CUR_MAX];
    int len = wctomb(mb, wc);
    printf("wide char '%lc' -> multibyte char [", wc);
    for (int idx = 0; idx < len; ++idx)
        printf("%s%#2x", idx ? " " : "", (unsigned char)mb[idx]);
    printf("]\n");
}
 
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    printf("MB_CUR_MAX = %zu\n", MB_CUR_MAX);
    demo(L'A');
    demo(L'\u00df');
    demo(L'\U0001d10b');
}

可能的输出：

MB_CUR_MAX = 6
State-dependent encoding? No.
wide char 'A' -> multibyte char [0x41]
State-dependent encoding? No.
wide char 'ß' -> multibyte char [0xc3 0x9f]
State-dependent encoding? No.
wide char '𝄋' -> multibyte char [0xf0 0x9d 0x84 0x8b]

引用

• C17 标准（ISO/IEC 9899:2018）：

• 7.22.7.3 The wctomb function （第 261 页）

• K.3.6.4.1 The wctomb_s function （第 443 页）

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

• 7.22.7.3 The wctomb function （第 358-359 页）

• K.3.6.4.1 The wctomb_s function （第 610-611 页）

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

• 7.20.7.3 The wctomb function （第 322-323 页）

• C89/C90 标准（ISO/IEC 9899:1990）：

• 4.10.7.3 The wctomb function

参阅

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