Namespaces
Variants

    wscanf, fwscanf, swscanf, wscanf_s, fwscanf_s, swscanf_s

    来自 zh.cppreference.net
    < c | io
     
    C
     
    文件输入/输出
    类型与对象
            
    函数
    文件访问
    (C11)
    (C11)  
    (C95)
    无格式输入/输出
    (C95)(C95)
    (C95)
    (C95)(C95)
    (C95)
    (C95)
    (C95)
    (C95)

    格式化输入
    (C99)(C99)(C99)(C11)(C11)(C11)
    (C99)(C99)(C99)(C11)(C11)(C11)  
     
    定义于头文件 <wchar.h> 
    int wscanf( const wchar_t* format, ... );
    		(1) (自 C95)
    (直至 C99)    		 
    int wscanf( const wchar_t* restrict format, ... );
    		(自 C99) 
    int fwscanf( FILE* stream, const wchar_t* format, ... );
    		(2) (自 C95)
    (直至 C99)    		 
    int fwscanf( FILE* restrict stream,
             const wchar_t* restrict format, ... );
    		(自 C99) 
    int swscanf( const wchar_t* buffer, const wchar_t* format, ... );
    		(3) (自 C95)
    (直至 C99)    		 
    int swscanf( const wchar_t* restrict buffer,
             const wchar_t* restrict format, ... );
    		(自 C99) 
    int wscanf_s( const wchar_t* restrict format, ...);
    		(4) (自 C11) 
    int fwscanf_s( FILE* restrict stream,
               const wchar_t* restrict format, ...);
    		(5) (自 C11) 
    int swscanf_s( const wchar_t* restrict s,
               const wchar_t* restrict format, ...);
    		(6) (自 C11)

    从多种来源读取数据，根据 format 对其进行解释，并将结果存储到指定位置。

    1) 从 stdin 读取数据。
    2) 从文件流 stream 读取数据。
    3) 从空终止宽字符串 buffer 读取数据。到达字符串末尾等同于到达 fwscanf
    的文件尾条件。4-6) 同 (1-3)%c，但 %s、%[ 和 转换说明符各自期望两个参数（通常的指针和一个类型为 rsize_t1 的值，指示接收数组的大小，当使用 %lc 读取单个宽字符时，该值可为 ），且以下错误会在运行时检测到，并调用当前已安装的 约束处理函数
    • ：
    • format任何指针类型的参数为空指针stream、buffer 或
    • 为空指针%c由 %s、%[ 或 rsize_t 将写入的字符数（加上终止空字符）会超出为这些转换说明符中每一个提供的第二个（
    • ）参数
    可选地，其他任何可检测到的错误，例如未知的转换说明符wscanf_s 与所有边界检查函数一样，fwscanf_s、swscanf_s 和 __STDC_LIB_EXT1__ 仅在实现定义了 __STDC_WANT_LIB_EXT1__，并且用户在包含 1wchar.h< 之前将 > 定义为整数常量

    参数

    stream - 要读取的输入文件流
    buffer - 指向要读取的以空字符结尾的宽字符串的指针
    format - 指向以空字符结尾的宽字符串的指针，指定如何读取输入
    ... - 接收参数。


    format 字符串由以下组成：

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

    可用的格式说明符如下：

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

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

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

    匹配一系列非空白字符（一个字符串）。

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

    匹配来自 集合 中的非空字符序列。

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

    匹配一个十进制整数。

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

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

    • 数字的格式与 wcstoul 以值 2 作为 base 参数时所期望的格式相同。
    i

    匹配一个整数。

    • 数字的格式与 wcstol 以值 0 作为 base 参数时所期望的格式相同（基数由解析的前几个字符确定）。
    u

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

    • 数字的格式与 wcstoul 以值 10 作为 base 参数时所期望的格式相同。
    o

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

    • 数字的格式与 wcstoul 以值 8 作为 base 参数时所期望的格式相同。
    x
    X

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

    • 数字的格式与 wcstoul 以值 16 作为 base 参数时所期望的格式相同。
    n

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

    • 不消耗输入。不会增加赋值的计数。
    • 如果说明符定义了赋值抑制运算符，则行为未定义。
    a （C99）
    A （C99）
    e
    E
    f
    F （C99）
    g
    G

    匹配一个浮点数。

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

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

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

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

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

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

    如果未使用长度说明符 l，则转换说明符 c、s 和 [ 会进行宽字符到多字节字符的转换，就像在转换第一个字符之前使用初始化为零的 mbstate_t 对象调用 wcrtomb 一样。

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

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

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

    当解析一个不完整的浮点值，该值以指数结束但没有数字时，例如使用转换说明符 "100er" 解析 %f，序列 "100e"（可能是有效浮点数的前缀）被消耗，导致匹配错误（消耗的序列无法转换为浮点数），并且 "r" 保留下来。一些现有的实现不遵循此规则，而是回滚以仅消耗 "100"，留下 "er"，例如 glibc 错误 1765。

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

    返回值

    1-3) 成功赋值的接收参数数量，若在首个接收参数被赋值前发生读取失败则返回 EOF
    4-6) 与 (1-3) 相同，不同之处在于当出现运行时约束违规时也会返回 EOF 。

    示例

    运行此代码
    #include <stdio.h>
#include <string.h>
#include <wchar.h>

#define NUM_VARS   3
#define ERR_READ   2
#define ERR_WRITE  3

int main(void)
{
    wchar_t state[64];
    wchar_t capital[64];
    unsigned int population = 0;
    int elevation = 0;
    int age = 0;
    float pi = 0;

#if INTERACTIVE_MODE
    wprintf(L"Enter state, age, and pi value: ");
    if (wscanf(L"%ls%d%f", state, &age, &pi) != NUM_VARS)
    {
        fprintf(stderr, "Error reading input.\n");
        return ERR_READ;
    }
#else
    wchar_t* input = L"California 170 3.141592";
    if (swscanf(input, L"%ls%d%f", state, &age, &pi) != NUM_VARS)
    {
        fprintf(stderr, "Error reading input.\n");
        return ERR_READ;
    }
#endif
    wprintf(L"State: %ls\nAge  : %d years\nPi   : %.5f\n\n", state, age, pi);

    FILE* fp = tmpfile();
    if (fp)
    {
        // write some data to temp file
        if (!fwprintf(fp, L"Mississippi Jackson 420000 807"))
        {
            fprintf(stderr, "Error writing to file.\n");
            fclose(fp);
            return ERR_WRITE;
        }
        // rewind file pointer
        rewind(fp);

        // read data into variables
        fwscanf(fp, L"%ls%ls%u%d", state, capital, &population, &elevation);
        wprintf(L"State  : %ls\nCapital: %ls\nJackson population (in 2020): %u\n"
                L"Highest elevation: %dft\n",
                state, capital, population, elevation);
        fclose(fp);
    }
}

    可能的输出： 

    State: California
Age  : 170 years
Pi   : 3.14159

State  : Mississippi
Capital: Jackson
Jackson population (in 2020): 420000
Highest elevation: 807ft

    参考

    • C23 标准（ISO/IEC 9899:2024）：
    • 7.29.2.2 fwscanf 函数（页：待定）
    • 7.29.2.4 swscanf 函数（页：待定）
    • 7.29.2.12 wscanf 函数（页：待定）
    • K.3.9.1.2 fwscanf_s 函数（页：待定）
    • K.3.9.1.5 swscanf_s 函数（页：待定）
    • K.3.9.1.14 wscanf_s 函数（页：待定）
    • C17 标准（ISO/IEC 9899:2018）：
    • 7.29.2.2 fwscanf 函数（页：待定）
    • 7.29.2.4 swscanf 函数（页：待定）
    • 7.29.2.12 wscanf 函数（页：待定）
    • K.3.9.1.2 fwscanf_s 函数（页：待定）
    • K.3.9.1.5 swscanf_s 函数（页：待定）
    • K.3.9.1.14 wscanf_s 函数（页：待定）
    • C11 标准（ISO/IEC 9899:2011）：
    • 7.29.2.2 fwscanf 函数（页：410-416）
    • 7.29.2.4 swscanf 函数（页：417）
    • 7.29.2.12 wscanf 函数（页：421）
    • K.3.9.1.2 fwscanf_s 函数（页：628-629）
    • K.3.9.1.5 swscanf_s 函数（页：631）
    • K.3.9.1.14 wscanf_s 函数（页：638）
    • C99 标准（ISO/IEC 9899:1999）：
    • 7.24.2.2 fwscanf 函数（页：356-362）
    • 7.24.2.4 swscanf 函数（页：362）
    • 7.24.2.12 wscanf 函数（页：366-367）

    参阅

    (C99)(C99)(C99)(C11)(C11)(C11)
    		 从stdin、文件流
    或缓冲区读取格式化宽字符输入，并使用可变参数列表
    (函数)
    C++ 文档关于wscanf、fwscanf、swscanf