Namespaces
Variants

std:: vwscanf, std:: vfwscanf, std:: vswscanf

From zh.cppreference.net
< cpp ‎ | io ‎ | c
定义于头文件 <cwchar>
int vwscanf ( const wchar_t * format, std :: va_list vlist ) ;
(1) (C++11 起)
int vfwscanf ( std:: FILE * stream, const wchar_t * format, std :: va_list vlist ) ;
(2) (C++11 起)
int vswscanf ( const wchar_t * buffer, const wchar_t * format, std :: va_list vlist ) ;
(3) (C++11 起)

从多种数据源读取数据,按照 format 格式进行解析,并将结果存储到由 vlist 定义的位置中。

1) 从 stdin 读取数据。
2) 从文件流 stream 中读取数据。
3) 从以空字符结尾的宽字符串 buffer 中读取数据。

目录

参数

stream — 要读取的输入文件流
buffer — 指向要读取的空终止宽字符串的指针
format — 指向指定如何读取输入的空终止宽字符串的指针
vlist — 包含接收参数的变量参数列表。


format 字符串由以下部分组成:

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

可用的格式说明符如下:

转换
说明符
说明 预期
参数类型
长度修饰符→ hh h 无 l ll j z t L
仅自 C++11 起可用→ 是 是 是 是 是
%
匹配字面量 %。
不适用 不适用 不适用 不适用 不适用 不适用 不适用 不适用 不适用
c

匹配一个 字符 或一组 字符。

  • 如果使用了宽度说明符,则精确匹配 width 个宽字符(参数必须是指向有足够空间的数组的指针)。
  • 与 %s 和  %[ 不同,不向数组追加空字符。
不适用 不适用
char*
wchar_t*
不适用 不适用 不适用 不适用 不适用
s

匹配一系列非空白字符(一个 字符串)。

  • 如果使用了宽度说明符,则匹配最多 width 个字符,或直到遇到第一个空白字符,以先到者为准。
  • 始终在匹配的字符之外额外存储一个空字符(因此参数数组必须至少能容纳 width+1 个字符)。
[集合 ]

匹配 集合 中的字符组成的非空序列。

  • 如果集合的第一个字符是 ^,则匹配所有不在集合中的字符。
  • 如果集合以 ] 或 ^] 开头,则 ] 字符也被包括在集合中。
  • 扫描集中非初始位置的字符 - 是否表示范围(如 [0-9])由实现定义。
  • 如果使用了宽度说明符,则最多匹配 width 个字符。
  • 始终在匹配的字符之外额外存储一个空字符(因此参数数组必须至少能容纳 width+1 个字符)。
d

匹配一个 十进制整数。

  • 数字格式与 std::wcstol 在 10 参数为 base 时预期的格式相同。
signed char* 或 unsigned char*
signed short* 或 unsigned short*
signed int* 或 unsigned int*
signed long* 或 unsigned long*
signed long long* 或 unsigned long long*
std::intmax_t* 或 std::uintmax_t*
std::size_t*
std::ptrdiff_t*
不适用
b (C++26)

匹配一个无符号 二进制整数。

  • 数字格式与 std::wcstoul 在 2 参数为 base 时预期的格式相同。
i

匹配一个 整数。

  • 数字格式与 std::wcstol 在 0 参数为 base 时预期的格式相同(基数由解析的前几个字符决定)。
u

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

  • 数字格式与 std::wcstoul 在 10 参数为 base 时预期的格式相同。
o

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

  • 数字格式与 std::wcstoul 在 8 参数为 base 时预期的格式相同。
x
X

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

  • 数字格式与 std::wcstoul 在 16 参数为 base 时预期的格式相同。
n

返回 到目前为止读取的字符数。

  • 不消耗任何输入。不增加赋值计数。
  • 如果说明符定义了赋值抑制操作符,则行为未定义。
a (C++11)
A (C++11)
e
E
f
F (C++11)
g
G

匹配一个 浮点数。

  • 数字格式与 std::wcstof 预期的格式相同。
不适用 不适用
float*
double*
不适用 不适用 不适用 不适用
long double*
p

匹配由实现定义的字符序列,表示一个 指针。

  • printf 系列函数应使用 %p 格式说明符生成相同的序列。
不适用 不适用
void**
不适用 不适用 不适用 不适用 不适用 不适用
注意

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

除 % 说明符外,输入项(或对于 %n,输入字符的数量)首先被转换为与转换说明符相适应的类型。除非使用 * 抑制了赋值,否则转换结果会被写入下一个尚未写入的参数所指向的对象。如果该对象没有合适的类型,或者转换结果无法在该对象中表示,则行为未定义。

除 [、c 和 n 之外的所有转换说明符在尝试解析输入之前,都会消耗并丢弃所有前导空白字符(通过调用 std::iswspace 判断)。这些消耗的字符不计入指定的最大字段宽度。

如果未使用长度说明符 l,则转换说明符 c、s 和 [ 会像调用 std::wcrtomb 一样执行宽字符到多字节字符的转换,并在转换第一个字符前将一个初始化为零的 std::mbstate_t 对象用于转换状态。

转换说明符 s 和 [ 始终在匹配的字符之外额外存储空终止符。目标数组的大小必须至少比指定的字段宽度大 1。如果不指定目标数组大小就使用 %s 或 %[,与 std::gets 同样不安全。

用于 定宽整数类型(std::int8_t 等)的正确转换说明符在头文件 <cinttypes> 中定义(尽管 SCNdMAX、SCNuMAX 等与 %jd、%ju 等是同义形式)。

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

当解析一个不完整的浮点值,且该值以没有数字的指数结尾时,例如使用转换说明符 "100er" 解析 %f,序列 "100e"(可能是有效浮点数的最大前缀)会被消耗,导致匹配错误(消耗的序列无法转换为浮点数),而 "r" 则保持不变。某些现有实现不遵循此规则,而是回退到仅消耗 "100",留下 "er",例如 glibc bug 1765。

如果转换说明无效,则行为未定义。

返回值

成功读取的参数数量,或 EOF 若发生读取失败。

示例

另请参阅

从 标准输入 、文件流或缓冲区读取格式化宽字符输入
(函数)
C 文档 关于 vwscanf 、 vfwscanf 、 vswscanf