Namespaces
Variants

wctomb, wctomb_s

From cppreference.net
C
Strings library
Null-terminated multibyte strings
定义于头文件 <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 不为零
与所有边界检查函数一样，仅当实现定义了 __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 - 指向输出参数的指针，用于存储结果（多字节序列长度或移位序列状态）

返回值

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 函数 (页码: 358-359)
  • K.3.6.4.1 wctomb_s 函数 (页码: 610-611)
  • C99标准（ISO/IEC 9899:1999）：
  • 7.20.7.3 wctomb函数（页码：322-323）
  • C89/C90 标准 (ISO/IEC 9899:1990):
  • 4.10.7.3 wctomb 函数

参见

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