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) char8_t (C23)	char16_t (C11) char32_t (C11)
宏
MB_LEN_MAX	MB_CUR_MAX

 

定义于头文件 <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) 相同，不同之处在于结果在 out-parameter status 中返回，并且在运行时检测到以下错误并调用当前安装的 约束处理函数

• ssz 小于将要写入的字节数（除非 s 为空）
• ssz 大于 RSIZE_MAX（除非 s 为空）
• s 是空指针，但 ssz 不为零

与所有边界检查函数一样，只有当实现定义了 __STDC_LIB_EXT1__ 并且用户在包含 <stdlib.h> 之前将 __STDC_WANT_LIB_EXT1__ 定义为整数常量 1 时，才能保证 wctomb_s 可用。

注解

每次调用 wctomb 都会更新内部全局转换状态（类型为 mbstate_t 的静态对象，仅对此函数已知）。如果多字节编码使用移位状态，则此函数不是可重入的。在任何情况下，多个线程不应在没有同步的情况下调用 wctomb：可以改用 wcrtomb 或 wctomb_s。

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

参数

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

返回值

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 wctomb 函数 (p: 261)

• K.3.6.4.1 wctomb_s 函数 (p: 443)

• C11 标准 (ISO/IEC 9899:2011)

• 7.22.7.3 wctomb 函数 (p: 358-359)

• K.3.6.4.1 wctomb_s 函数 (p: 610-611)

• C99 标准 (ISO/IEC 9899:1999)

• 7.20.7.3 wctomb 函数 (p: 322-323)

• C89/C90 标准 (ISO/IEC 9899:1990)

• 4.10.7.3 wctomb 函数

参见

mbtowc	将下一个多字节字符转换为宽字符 (函数)
wcrtombwcrtomb_s (C95)(C11)	在给定状态下，将宽字符转换为其多字节表示形式 (函数)
C++ 文档，关于 wctomb