C Library User 手册(25)

C Library User 手册（25）

10.26 wchar.h
- 10.26.1 btowc
- 10.26.2 fgetwc
- 10.26.3 fgetws
- 10.26.4 fputwc
- 10.26.5 fputws
- 10.26.6 fwide
- 10.26.7 fwprintf
- 10.26.8 fwscanf
- 10.26.9 getwc
- 10.26.10 getwchar
- 10.26.11 mbrlen
- 10.26.12 mbrtowc
- 10.26.13 mbsinit
- 10.26.14 mbsrtowcs
- 10.26.15 mbstate_t
- 10.26.16 NULL
- 10.26.17 putwc
- 10.26.18 putwchar
- 10.26.19 size_t
- 10.26.20 swprintf
- 10.26.21 swscanf
- 10.26.22 tm
- 10.26.23 ungetwc
- 10.26.24 vfwprintf
- 10.26.25 vswprintf
- 10.26.26 vwprintf

10.26 wchar.h

包括标准头 <wchar.h> 以便你可以对宽流执行输入和输出操作或操作宽字符串。

10.26.1 btowc

wint_t btowc(int c);

如果 c 等于 EOF，则函数返回 WEOF。否则，它将 (unsigned char)c 转换为从初始转换状态开始的单字节多字节字符，就像调用 mbrtowc 一样。如果转换成功，函数返回宽字符转换。否则，它返回 WEOF。

10.26.2 fgetwc

wint_t fgetwc(FILE *stream);

该函数从输入流中读取下一个宽字符 c（如果存在），前进文件位置指示符（如果已定义），然后返回 (wint_t)c。如果函数设置了文件结束指示符或错误指示符，则返回 WEOF。

10.26.3 fgetws

wchar_t *fgetws(wchar_t *restrict s, int n, FILE *restrict stream);

该函数从输入流中读取宽字符，并将它们存储在数组的连续元素中，从沙子开始，直到它存储 n-1 个宽字符，存储一个 NL 宽字符，或设置文件结尾或错误指示符。如果 fgetws 存储任何宽字符，它会在数组的下一个元素中存储一个空宽字符来结束。如果它存储了任何宽字符并且没有为流设置错误指示符，则返回 s；否则，它返回一个空指针。如果它设置了错误指示符，则数组内容是不确定的。

10.26.4 fputwc

wint_t fputwc(wchar_t c, FILE *stream);

该函数将宽字符 c 写入输出流流，推进文件位置指示符（如果已定义），并返回 (wint_t )c。如果函数为流设置错误指示符，则返回 WEOF

10.26.5 fputws

int fputws(const wchar_t *restrict s, FILE *restrict stream);

该函数访问字符串 s 中的宽字符并将它们写入输出流流。该函数不写入终止的空宽字符。如果未设置错误指示符，则返回非负值；否则，它返回 WEOF。

10.26.6 fwide

int fwide(FILE *stream, int mode);

该函数确定流流的方向。如果模式大于零，它首先尝试使流面向宽。如果 mode 小于零，它首先尝试使流字节定向。无论如何，该函数返回：

如果流是面向左宽的，则值大于零
如果流未绑定，则为零
如果流是面向左字节的，则值小于零

10.26.7 fwprintf

int fwprintf(FILE *restrict stream, const wchar_t *restrict format,...);

该函数在格式格式和任何附加参数的控制下生成格式化文本，并将每个生成的宽字符写入流流。它返回生成的宽字符数，或者如果函数为流设置错误指示符，则返回负值。

10.26.8 fwscanf

int fwscanf(FILE *restrict stream, const wchar_t *restrict format,...);

该函数在格式格式和任何附加参数的控制下扫描格式化文本。它从流中获取每个扫描的字符。它返回匹配和分配的输入项的数量，或者如果函数在为流设置文件结尾或错误指示符之前未存储值，则返回 EOF。

10.26.9 getwc

wint_t getwc(FILE *stream);

该函数与 fgetwc(stream) 具有相同的效果，只是 getwc 的宏版本可以多次评估流。

10.26.10 getwchar

wint_t getwchar(void);

该函数与 fgetwc(stdin) 的作用相同。

10.26.11 mbrlen

size_t mbrlen(const char *restrict s, size_t n, mbstate_t *restrictps);
该函数相当于调用：
mbrtowc (0, s, n, ps != 0 ? ps : &internal)

其中 internal 是 mbrlen 函数内部的 mbstate_t 类型的对象。在程序启动时，内部被初始化为初始转换状态。没有其他库函数改变存储在 internal 中的值。

函数返回：

(size_t)-3 如果不需要额外的字节来完成下一个多字节字符，在这种情况下，生成的转换状态表明没有额外的字节被转换并且下一个多字节字符已经产生
(size_t)-2 如果在转换所有 n 个字符后，结果转换状态指示不完整的多字节字符
(size_t)-1，如果函数在完成下一个多字节字符之前检测到编码错误，在这种情况下，函数将值 EILSEQ 存储在 errno 中，并使生成的转换状态未定义
0(零)，如果下一个完整字符是空字符，在这种情况下，生成的转换状态是初始转换状态
x，完成下一个多字节字符所需的字节数，在这种情况下，生成的转换状态指示已转换 x 个字节并且已生成下一个多字节字符

因此，mbrlen 有效地返回成功将多字节字符转换为宽字符（不存储转换后的宽字符）所消耗的字节数，或者如果转换不能成功，则返回错误代码。

10.26.12 mbrtowc

size_t mbrtowc(wchar_t *restrict pwc, const char *restrict s,size_t n, mbstate_t *restrict ps);

如果可能，该函数确定完成下一个多字节字符的多字节字符串中的字节数。

如果 ps 不是空指针，则假定多字节字符串的转换状态为 *ps。否则，假定为 &internal，其中 internal 是 mbrtowc 函数内部的 mbstate_t 类型的对象。在程序启动时，内部被初始化为初始转换状态。没有其他库函数会更改存储在 internal 中的值。

如果 s 不是空指针，则函数确定 x，即多字节字符串 s 中完成或构成下一个多字节字符的字节数。（x 不能大于 n。）否则，函数有效地返回 mbrtowc(0, “”, 1, ps)，忽略 pwc 和 n。（因此，仅当转换状态表明对于相同字符串和转换状态的先前调用 mbrlen、mbrtowc 或 mbsrtowcs 没有未完成的多字节字符时，该函数才返回零。）

如果 pwc 不是空指针，则该函数将完成的多字节字符转换为其对应的宽字符值并将该值存储在 *pwc 中。

函数返回：

(size_t)-3 如果不需要额外的字节来完成下一个多字节字符，在这种情况下，生成的转换状态表明没有额外的字节被转换并且下一个多字节字符已经产生
(size_t)-2 如果在转换所有 n 个字符后，结果转换状态指示不完整的多字节字符
(size_t)-1，如果函数在完成下一个多字节字符之前检测到编码错误，在这种情况下，函数将值 EILSEQ 存储在 errno 中，并使生成的转换状态未定义
0(零)，如果下一个完整字符是空字符，在这种情况下，生成的转换状态是初始转换状态
x，完成下一个多字节字符所需的字节数，在这种情况下，生成的转换状态指示已转换 x 个字节并且已生成下一个多字节字符

10.26.13 mbsinit

int mbsinit(const mbstate_t *ps);

如果 ps 是空指针或 *ps 指定初始转换状态，则该函数返回非零值。否则，它返回零。

10.26.14 mbsrtowcs

size_t mbsrtowcs(wchar_t *restrict dst, const char **restrict src,size_t len, mbstate_t *restrict ps);

该函数将从 *src 开始的多字节字符串转换为宽字符序列，就好像通过重复调用以下形式：
x = mbrtowc(dst, *src, n, ps != 0 ? ps : &internal)

其中 n 是某个 > 0 的值，internal 是 mbsrtowcs 函数内部的 mbstate_t 类型的对象。在程序启动时，内部被初始化为初始转换状态。没有其他库函数会更改存储在 internal 中的值。

如果 dst 不是空指针，则 mbsrtowcs 函数通过调用 mbrtowc 最多存储 len 宽的字符。每次调用存储转换后的宽字符的 mbrtowc 后，该函数有效地将 dst 增加 1 和 *src 增加 x。在返回零的调用之后，mbsrtowcs 将一个空宽字符存储在 dst 并在 *src 存储一个空指针。

如果 dst 是一个空指针，则 len 被有效地分配了一个大值。

函数返回：

(size_t)-1，如果调用 mbrtowc 返回 (size_t)-1，表示在完成下一个多字节字符之前检测到编码错误
成功转换的多字节字符数，不包括终止空字符

10.26.15 mbstate_t

typedef o-type mbstate_t;
该类型是一个对象类型 o-type，可以表示任何函数 mbrlen、mbrtowc、mbsrtowcs、wcrtomb 或 wcsrtombs 的转换状态。形式的定义：
mbstate_t mbst = {0};
确保 mbst 表示初始转换状态。但是请注意，存储在 typembstate_t 对象中的其他值也可以表示此状态。要安全地测试此状态，请使用函数 mbsinit。

10.26.16 NULL

#define NULL <either 0, 0L, or (void *)0> [0 in C++]
该宏产生一个可用作地址常量表达式的空指针常量。

10.26.17 putwc

wint_t putwc(wchar_t c, FILE *stream);
该函数与 fputwc(c, stream) 具有相同的效果，只是 putwc 的宏版本可以多次评估流。

10.26.18 putwchar

wint_t putwchar(wchar_t c);
该函数与 fputwc(c, stdout) 的效果相同。

10.26.19 size_t

typedef ui-type size_t;
该类型是你声明用于存储 sizeof 运算符结果的对象的无符号整数类型 ui-type。

10.26.20 swprintf

int swprintf(wchar_t *restrict s, size_t n, const wchar_t *restrict format, ...);

该函数在格式格式和任何附加参数的控制下生成格式化文本，并将每个生成的字符存储在第一个元素具有地址 s 的数组对象的连续位置中。该函数通过在数组的下一个位置存储一个空宽字符来结束。如果它不能在大小为 n 的数组中生成和存储所有字符，则该函数返回一个负数。否则，它返回生成的宽字符数——不包括空宽字符。

10.26.21 swscanf

int swscanf(const wchar_t *restrict s, const wchar_t *restrict format, ...);
该函数在格式格式和任何附加参数的控制下扫描格式化文本。它从第一个元素的地址为 s 的数组对象的连续位置访问每个扫描的字符。它返回匹配和分配的项目数，或者如果函数在访问数组中的空宽字符之前未存储值，则返回 EOF。

10.26.22 tm

struct tm;
struct tm 包含描述日历时间的各种属性的成员。此标头中的声明使 struct tm 成为不完整的类型。包括标题 <time.h> 以完成类型。

10.26.23 ungetwc

wint_t ungetwc(wint_t c, FILE *stream);
如果 c 不等于 WEOF，则函数将 (wchar_t)c 存储在地址为流的对象中并清除文件结束指示符。如果 c 等于 WEOF 或存储不能发生，则函数返回 WEOF；否则，它返回 (wchar_t)c。从流流中读取宽字符的后续库函数调用获取此存储值，然后将其遗忘。

因此，你可以在读取宽字符后有效地将宽字符推回流。

10.26.24 vfwprintf

int vfwprintf(FILE *restrict stream, const wchar_t *restrict format, va_list arg);

该函数通过使用 ap 指定的上下文信息来访问附加参数。程序必须在调用函数之前执行宏va_start，然后在函数返回后执行宏va_end。

10.26.25 vswprintf

int vswprintf(wchar_t *restrict s, size_t n, const wchar_t *restrict format, va_list arg);

该函数在格式格式和任何附加参数的控制下生成格式化文本，并将每个生成的宽字符存储在第一个元素具有地址 s 的数组对象的连续位置中。该函数通过在数组的下一个位置存储一个空宽字符来结束。如果它不能在大小为 n 的数组中生成和存储所有字符，则该函数返回一个负数。否则，它返回生成的宽字符数——不包括空宽字符。

该函数通过使用 ap 指定的上下文信息来访问附加参数。程序必须在调用函数之前执行宏va_start，然后在函数返回后执行宏va_end。

10.26.26 vwprintf

int vwprintf(const wchar_t *restrict format, va_list arg);

该函数在格式格式和任何附加参数的控制下生成格式化文本，并将每个生成的宽字符写入流标准输出。它返回生成的字符数，如果函数为流设置错误指示符，则返回负值。

该函数通过使用 ap 指定的上下文信息来访问附加参数。程序必须在调用函数之前执行宏va_start，然后在函数返回后执行宏va_end。