wctomb, wctomb_s

来自cppreference.com
< c‎ | string‎ | multibyte
定义于头文件 <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
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:可使用wcrtombwctomb_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)
{
    printf("State-dependent encoding?   %d\n", wctomb(NULL, wc));
 
    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("%#2x ", (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?   0
wide char 'A' -> multibyte char '0x41 '
State-dependent encoding?   0
wide char 'ß' -> multibyte char '0xc3 0x9f '
State-dependent encoding?   0
wide char '𝄋' -> multibyte char '0xf0 0x9d 0x84 0x8b '

[编辑] 参考

  • C11 standard (ISO/IEC 9899:2011):
  • 7.22.7.3 The wctomb function (p: 358-359)
  • K.3.6.4.1 The wctomb_s function (p: 610-611)
  • C99 standard (ISO/IEC 9899:1999):
  • 7.20.7.3 The wctomb function (p: 322-323)
  • C89/C90 standard (ISO/IEC 9899:1990):
  • 4.10.7.3 The wctomb function

[编辑] 参阅

将下一个多字节字符转换成宽字符
(函数) [编辑]
给定状态,将宽字符转换成其多字节表示
(函数) [编辑]
wctombC++ 文档