wcrtomb, wcrtomb_s
定义于头文件 <wchar.h>
|
||
(1) | ||
(C95 起) | ||
(C99 起) | ||
(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
所指向的字符数组的字节数(包含任何迁移序列)。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 ", in[n]); puts("]"); char out[MB_CUR_MAX * in_sz]; char *p = out; for(size_t n = 0; n < in_sz; ++n) { size_t rc = wcrtomb(p, in[n], &state); if(rc == (size_t)-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 standard (ISO/IEC 9899:2011):
- 7.29.6.3.3 The wcrtomb function (p: 444)
- K.3.9.3.1.1 The wcrtomb_s function (p: 647-648)
- C99 standard (ISO/IEC 9899:1999):
- 7.24.6.3.3 The wcrtomb function (p: 390)
参阅
(C11) |
将宽字符转换成其多字节表示 (函数) |
(C95) |
给定状态,将下一个多字节字符转换成宽字符 (函数) |