命名空间
变体
操作

vwscanf、vfwscanf、vswscanf、vwscanf_s、vfwscanf_s、vswscanf_s

来自 cppreference.com
< c‎ | io
 
 
文件输入/输出
类型和对象
函数
文件访问
直接输入/输出
非格式化输入/输出
(C95)(C95)
(C95)
(C95)(C95)
(C95)
(C95)
格式化输入
vwscanfvfwscanfvswscanfvwscanf_svfwscanf_svswscanf_s
(C99)(C99)(C99)(C11)(C11)(C11)     
 
定义在头文件 <wchar.h>
int vwscanf( const wchar_t *restrict format, va_list vlist );
(1) (自 C99)
int vfwscanf( FILE *restrict stream,
              const wchar_t *restrict format, va_list vlist );
(2) (自 C99)
int vswscanf( const wchar_t *restrict buffer,
              const wchar_t *restrict format, va_list vlist );
(3) (自 C99)
int vwscanf_s( const wchar_t *restrict format, va_list vlist );
(4) (自 C11)
int vfwscanf_s( FILE *restrict stream,
                const wchar_t *restrict format, va_list vlist );
(5) (自 C11)
int vswscanf_s( const wchar_t *restrict buffer,
                const wchar_t *restrict format, va_list vlist );
(6) (自 C11)

从各种来源读取数据,根据 format 解释数据,并将结果存储到由 vlist 定义的位置。

1)stdin 读取数据。
2) 从文件流 stream 读取数据。
3) 从以空字符结尾的宽字符串 buffer 读取数据。到达字符串末尾等同于 fwscanf 的文件结束条件。
4-6)(1-3) 相同,但 %c%s%[ 转换说明符分别期望两个参数(通常的指针和一个 rsize_t 类型的值,指示接收数组的大小,当使用 %lc 读取单个宽字符时,该值可能为 1),并除外运行时检测到以下错误并调用当前安装的 约束处理程序 函数
  • 任何指针类型的参数都是空指针
  • formatstreambuffer 是空指针
  • 由 %c, %s 或 %[, 加上终止空字符写入的字符数将超过为每个转换说明符提供的第二个(rsize_t)参数
  • 可选地,任何其他可检测到的错误,例如未知转换说明符
与所有有界检查函数一样,vwscanf_svfwscanf_svswscanf_s 仅在实现定义了 __STDC_LIB_EXT1__ 并且用户在包含 <stdio.h> 之前将 __STDC_WANT_LIB_EXT1__ 定义为整型常量 1 时才保证可用。

内容

[编辑] 参数

stream - 要从中读取的输入文件流
buffer - 指向要从中读取的以空字符结尾的宽字符串的指针
format - 指向指定如何读取输入的以空字符结尾的宽字符串的指针
vlist - 包含接收参数的可变参数列表。


format 字符串包含

  • 非空白宽字符,除了 % 之外:格式字符串中的每个这样的字符都从输入流中消耗一个完全相同的字符,或者如果流上的下一个字符不等于比较,则导致函数失败。
  • 空白字符:格式字符串中的任何单个空白字符都消耗输入流中所有可用的连续空白字符(通过循环调用 iswspace 来确定)。请注意,"\n"" ""\t\t" 或格式字符串中的其他空白之间没有区别。
  • 转换说明符。每个转换说明符都具有以下格式
  • 介绍性的 % 字符。
  • (可选) 赋值抑制字符 *。如果存在此选项,则函数不会将转换结果分配给任何接收参数。
  • (可选) 整型数字(大于零),指定最大字段宽度,即函数在进行当前转换说明符指定的转换时允许消耗的字符的最大数量。请注意,%s%[ 如果没有提供宽度,可能会导致缓冲区溢出。
  • (可选) 长度修饰符,指定接收参数的大小,即实际目标类型。这会影响转换精度和溢出规则。默认目标类型对于每种转换类型都不同(见下表)。
  • 转换格式说明符。

以下格式说明符可用

转换
说明符
解释 参数类型
长度修饰符 →
hh

(C99)

h (无) l ll

(C99)

j

(C99)

z

(C99)

t

(C99)

L
% 匹配文字 % N/A N/A N/A N/A N/A N/A N/A N/A N/A
c
匹配一个字符字符序列。

如果使用宽度说明符,则匹配恰好宽度个宽字符(参数必须是指向具有足够空间的数组的指针)。与 %s 和 %[, 不同,它不会在数组末尾附加空字符。

N/A N/A
char*
wchar_t*
N/A N/A N/A N/A N/A
s
匹配非空白字符序列(字符串)。

如果使用宽度说明符,则匹配最多 width 个字符,或直到遇到第一个空格字符,以先出现的为准。始终存储一个空字符,除了匹配到的字符(因此参数数组必须至少有 width+1 个字符的空间)。

[set]
匹配来自 set 字符集的非空字符序列。

如果字符集的第一个字符是 ^,则匹配字符集中没有的字符。如果字符集以 ]^] 开头,则 ] 字符也包含在字符集中。在扫描集的非初始位置,字符 - 是否表示范围(如 [0-9])是实现定义的。如果使用宽度说明符,则只匹配最多 width 个字符。始终存储一个空字符,除了匹配到的字符(因此参数数组必须至少有 width+1 个字符的空间)。

d
匹配一个十进制整数

数字格式与 wcstol 函数预期的一致,其中 base 参数的值为 10

signed char*unsigned char*
signed short*unsigned short*
signed int*unsigned int*
signed long*unsigned long*
signed long long*unsigned long long*
N/A
i
匹配一个整数

数字格式与 wcstol 函数预期的一致,其中 base 参数的值为 0(底数由解析的第一个字符决定)。

u
匹配一个无符号十进制整数

数字格式与 wcstoul 函数预期的一致,其中 base 参数的值为 10

o
匹配一个无符号八进制整数

数字格式与 wcstoul 函数预期的一致,其中 base 参数的值为 8

x, X
匹配一个无符号十六进制整数

数字格式与 wcstoul 函数预期的一致,其中 base 参数的值为 16

n
返回迄今为止读取的字符数

不消耗任何输入。不增加赋值计数。如果说明符有赋值抑制运算符,则行为未定义。

a, A(C99)
e, E
f, F(C99)
g, G
匹配一个浮点数

数字格式与 wcstof 函数预期的一致。

N/A N/A
float*
double*
N/A N/A N/A N/A
long double*
p
匹配定义指针的实现定义的字符序列。

printf 函数系列应该使用 %p 格式说明符生成相同的序列。

N/A N/A
void**
N/A N/A N/A N/A N/A N/A

对于除 n 之外的所有转换说明符,从流中消耗的最长输入字符序列,不超过任何指定的字段宽度,并且要么完全符合转换说明符的预期,要么是它将预期的序列的前缀,是输入流中消耗的序列。第一个字符,如果有的话,在该消耗序列之后保持未读。如果消耗的序列的长度为零,或者消耗的序列无法按上述方式转换,则会发生匹配失败,除非文件结束、编码错误或读取错误阻止了来自流的输入,在这种情况下,它是一个输入失败。

除了 [cn 之外的所有转换说明符,在尝试解析输入之前,会消耗并丢弃所有前导空白字符(确定方式与调用 iswspace 函数相同)。这些消耗的字符不计入指定的最大字段宽度。

如果未使用长度说明符 l,则转换说明符 cs[ 将执行宽字符到多字节字符的转换,方式与在第一个字符转换之前使用值为零的 mbstate_t 对象调用 wcrtomb 函数相同。

转换说明符 s[ 始终在匹配的字符之外存储空终止符。目标数组的大小必须至少比指定的字段宽度大一个。使用 %s%[,不指定目标数组大小,与 gets 一样不安全。

针对 固定宽度整数类型int8_t 等)的正确转换规范定义在头文件 <inttypes.h> 中(尽管 SCNdMAXSCNuMAX 等与 %jd%ju 等是同义词)。

在每个转换说明符的操作之后有一个 序列点;这允许将多个字段存储在相同的“接收器”变量中。

当解析以指数结尾但没有数字的不完整浮点数时,例如使用转换说明符 "100er" 解析 %f,序列 "100e"(可能有效的浮点数的最长前缀)被消耗,导致匹配错误(消耗的序列无法转换为浮点数),"r" 仍然存在。一些现有实现不遵循此规则,而是回滚以仅消耗 "100",留下 "er",例如 glibc 错误 1765

[edit] 返回值

1-3) 成功分配的接收参数数量,或者如果在分配第一个接收参数之前发生读取失败,则返回 EOF
4-6)(1-3) 相同,只是如果存在运行时约束违反,也会返回 EOF

[edit] 注意

所有这些函数都可能调用 va_arg,在返回后,arg 的值是不确定的。这些函数不会调用 va_end,必须由调用者完成。

[edit] 示例

[edit] 参考资料

  • C11 标准(ISO/IEC 9899:2011)
  • 7.29.2.6 vfwscanf 函数(第 418 页)
  • 7.29.2.8 vswscanf 函数(第 419 页)
  • 7.29.2.10 vwscanf 函数(第 420 页)
  • K.3.9.1.7 vfwscanf_s 函数(第 632-633 页)
  • K.3.9.1.10 vswscanf_s 函数(第 635-636 页)
  • K.3.9.1.12 vwscanf_s 函数(第 637 页)
  • C99 标准(ISO/IEC 9899:1999)
  • 7.24.2.6 vfwscanf 函数(第 364 页)
  • 7.24.2.8 vswscanf 函数(第 365 页)
  • 7.24.2.10 vwscanf 函数(第 366 页)

[edit] 另请参阅

stdin、文件流或缓冲区读取格式化的宽字符输入。
(function) [edit]
C++ 文档 适用于 vwscanf, vfwscanf, vswscanf