| int vscanf( const char* format, va_list vlist ); |
(1) |
(C++11 起) |
int vfscanf( std::FILE* stream, const char* format, va_list vlist ); |
(2) |
(C++11 起) |
| int vsscanf( const char* buffer, const char* format, va_list vlist ); |
(3) |
(C++11 起) |
| | |
从各种源读取数据，按照 format 转译并存储结果到 vlist 所定义的位置。
2) 从文件流 stream 读取数据。
3) 从空终止字符串 buffer 读取数据。
参数
| stream
|
-
|
要读取的输入文件流
|
| buffer
|
-
|
指向要读取的空终止字符串的指针
|
| format
|
-
|
指向指定如何读取输入的空终止字符串的指针。
格式字符串由下列内容组成
- 非空白多字节字符，除了
% ：每个格式字符串中的这种字符处理来自输入流的准确同一字符，或若它与流的下个字符比较不相等则导致函数失败。
- 空白符：任何格式字符串中的单个空白符处理所有来自输入的可用连续空白符（如同通过于循环中调用 isspace 确定）。注意格式字符串中 "\n" 、 " " 、 "\t\t" 或其他空白无区别。
- 转换说明：每个转换说明拥有下列格式：
-
- (可选)赋值抑制字符
* 。若存在此选项，则此函数不将结果赋值给任何接收用参数。
- (可选)指定最大域宽的整数数字（大于零），即函数进行在当前转换说明所指定的转换时，允许处理的最大字符数。注意若不提供宽度，则 %s 和 %[ 可能导致缓冲区溢出。
- (可选)指定接收参数大小的长度修饰符，即实际目标类型。这影响转换准确性和溢出规则。默认目标类型对每个转换类型不同（见下表）。
-
下列格式说明符可用：
转换
说明符
|
解释
|
参数类型
|
| 长度修饰符 →
|
hh
(C++11)
|
h
|
（无）
|
l
|
ll
(C++11)
|
j
(C++11)
|
z
(C++11)
|
t
(C++11)
|
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
|
|
|
N/A
|
N/A
|
N/A
|
N/A
|
N/A
|
s
|
- 匹配非空白字符的序列（一个字符串）
若使用宽度说明符，则至多匹配宽度个字符，或匹配到首个提前出现的空白符前。总是在匹配的字符后存储一个空字符（故参数数组必须有至少宽度 +1 个字符的空间）。
|
[集合]
|
- 匹配一个来自 集合 的字符的非空字符序列。
若集合的首字符是 ^ ，则匹配所有不在集合中的字符。若集合以 ] 或 ^] 开始，则 ] 字符亦被包含入集合。在扫描集合的非最初位置的字符 - 是否可以指示范围，如 [0-9] ，是实现定义的。若使用宽度说明符，则最多匹配到宽度。总是在匹配的字符后存储一个空字符（故参数数组必须有至少宽度 +1 个字符的空间）。
|
d
|
- 匹配一个十进制整数。
该数的格式同 strtol() 以值 10 为 base 时所期望者
|
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
|
- 匹配一个整数。
该数的格式同 strtol() 以值 0 为 base 时所期望者（基底以首个分析的字符确定）
|
u
|
- 匹配一个无符号十进制整数。
该数的格式同 strtoul() 以值 10 为 base 参数时所期望者。
|
o
|
- 匹配一个无符号八进制数。
该数的格式同 strtoul() 以值 8 为 base 参数时所期望者。
|
x, X
|
- 匹配一个无符号十六进制整数。
该数的格式同 strtoul() 以值 16 为 base 参数时所期望者。
|
n
|
- 返回迄今读取的字符数。
不消耗输出。不增加赋值计数。若此说明符拥有赋值抑制运算符，则行为未定义。
|
a, A(C++11)
e, E
f, F
g, G
|
- 匹配一个浮点数。
该数的格式同 strtof() 所期望者。
|
N/A
|
N/A
|
|
|
N/A
|
N/A
|
N/A
|
N/A
|
|
p
|
- 匹配定义一个指针的实现定义的字符序列。
printf 系列函数应该用 %p 格式说明符产生同样的序列。
|
N/A
|
N/A
|
|
N/A
|
N/A
|
N/A
|
N/A
|
N/A
|
N/A
|
对于每个异于 n 的转换说明符，不超过任何指定域宽，且要么是转换说明符所准确期待，要么是其所期待的前缀的最长输入字符序列，即是从流中消耗的内容。此消耗序列后的首个字符若存在，则保持未读取。若被消耗序列长度为零，或被消耗序列不能转换成上面所指定的项目，则发生匹配失败，除非遇到文件尾、编码错误，或阻止从流输入的读取错误，此情况下此为输入失败。
所有异于 [ 、 c 和 n 的转换说明符，在尝试分析输入前消耗并舍弃所有前导空白字符（如同以调用 isspace 来确定）。这些被消耗的字符不计入指定的最大域宽。
转换说明符 lc 、 ls 和 l[ 进行多字节到宽字符转换，如同如同在转换首字符前，通过用初始化到零的 mbstate_t 对象调用 mbrtowc() 。
转换说明符 s 与 [ 始终在匹配字符之后存储一个空字符。目标数组的大小必须至少比指定域宽大一。
定宽整数类型（ int8_t 等）的正确的转换说明定义于头文件 <cinttypes> （虽然 SCNdMAX 、 SCNuMAX 等就是 %jd 、 %ju 等的别名）。
在每个转换说明符后有一个序列点；这允许存储多个域到同一“池”变量中。
在分析以无数字指数为结尾的不完整浮点值，如以转换说明符 %f 分析 "100er" 时，消耗序列 "100e" （可能为合法浮点数的最长前缀），并导致匹配错误（被消耗序列不能转换成浮点数），而留下 "r" 。某些既存实现不遵守此规则并回滚，通过消耗 "100" 而留下 "er" ，例如 glibc 漏洞 1765 。
|
| vlist
|
-
|
含有接收参数的可变参数列表
|
返回值
成功读取的参数个数，或若出现失败则为 EOF 。
注解
所有这些函数调用 va_arg 至少一次，返回后 arg 的值不确定。这些函数不调用 va_end ，而这必须由调用方进行。
示例
#include <iostream>
#include <cstdio>
#include <cstdarg>
#include <stdexcept>
void checked_sscanf(int count, const char* buf, const char *fmt, ...)
{
va_list ap;
va_start(ap, fmt);
if(std::vsscanf(buf, fmt, ap) != count)
throw std::runtime_error("parsing error");
va_end(ap);
}
int main()
{
try {
int n, m;
std::cout << "Parsing '1 2'...";
checked_sscanf(2, "1 2", "%d %d", &n, &m);
std::cout << "success\n";
std::cout << "Parsing '1 a'...";
checked_sscanf(2, "1 a", "%d %d", &n, &m);
std::cout << "success\n";
} catch(const std::exception& e)
{
std::cout << e.what() << '\n';
}
}输出：
Parsing '1 2'...success
Parsing '1 a'...parsing error
参阅
|
|
从 stdin、文件流或缓冲区读取有格式输入
(函数) |
|
|
使用可变实参列表
打印有格式输出到 stdout、文件流或缓冲区
(函数) |