Namespaces
Variants

    std:: vscanf, std:: vfscanf, std:: vsscanf

    From zh.cppreference.net
    < cpp ‎ | io ‎ | c
    C++
    Input/output library
    C-style I/O
    定义于头文件 <cstdio>
    int vscanf ( const char * format, std :: va_list vlist ) ;
    		(1) (C++11 起)
    int vfscanf ( std:: FILE * stream, const char * format, std :: va_list vlist ) ;
    		(2) (C++11 起)
    int vsscanf ( const char * buffer, const char * format, std :: va_list vlist ) ;
    		(3) (C++11 起)

    从多种来源读取数据，根据 format 进行解析，并将结果存储到由 vlist 定义的位置中。

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

    目录

    参数

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


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

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

    可用的格式说明符如下：

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

    匹配一个 字符 或一个 字符 序列。

    • 如果使用宽度说明符，则正好匹配 width 个字符（参数必须是指向具有足够空间的数组的指针）。
    • 与 %s 和  %[ 不同，它不会向数组追加空字符。
    		 不适用 不适用
    char*
    wchar_t*
    		 不适用 不适用 不适用 不适用 不适用
    s

    匹配非空白字符序列（字符串）。

    • 如果使用宽度说明符，则最多匹配 width 个字符，或直到第一个空白字符，以先出现者为准。
    • 除了匹配的字符外，始终存储一个空字符（因此参数数组必须至少容纳 width+1 个字符）。
    [集合 ]

    匹配一个来自于 set 字符集的非空字符序列。

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

    匹配一个 十进制整数。

    • 数字的格式与 std::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*
    std::intmax_t* 或 std::uintmax_t*
    std::size_t*
    std::ptrdiff_t*
    		 不适用
    b （C++26）

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

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

    匹配一个 整数。

    • 数字的格式与 std::strtol 在 0 为 base 参数时预期的格式相同（基数由解析的首个字符确定）。
    u

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

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

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

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

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

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

    返回迄今读取的字符数。

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

    匹配一个浮点数。

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

    匹配由实现定义的字符序列，该序列定义一个指针。

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

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

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

    除 [、c 和 n 之外的所有转换说明符在尝试解析输入之前，都会消耗并丢弃所有前导空白字符（如同通过调用 std::isspace 确定）。这些被消耗的字符不计入指定的最大字段宽度。

    转换说明符 lc、ls 和 l[ 执行多字节到宽字符的转换，如同在转换第一个字符之前将一个初始化为零的 std::mbstate_t 对象传递给 std::mbrtowc 进行转换。

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

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

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

    当解析一个不完整的浮点值（例如以指数结尾但没有数字，如解析 "100er" 并带有转换说明符 %f 时），序列 "100e"（可能为有效浮点数的最长前缀）被消耗，导致匹配错误（消耗的序列无法转换为浮点数），而 "r" 剩余。一些现有实现不遵循此规则并回退，只消耗 "100"，留下 "er"，例如 glibc bug 1765。

    如果转换规格说明无效，则行为未定义。

    返回值

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

    注释

    所有这些函数至少调用一次 va_arg ，返回后 arg 的值是不确定的。这些函数不会调用 va_end ，必须由调用者完成此操作。

    示例

    运行此代码 
    #include <cstdarg>
#include <cstdio>
#include <iostream>
#include <stdexcept>
void checked_sscanf(int count, const char* buf, const char *fmt, ...)
{
    std::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

    另请参阅

    		从 标准输入 、文件流或缓冲区读取格式化输入
    （函数）
    (C++11)
    		使用可变参数列表将格式化输出打印到 标准输出 、文件流或缓冲区
    （函数）
    C 文档 关于 vscanf 、 vfscanf 、 vsscanf