Namespaces
Variants

wscanf, fwscanf, swscanf, wscanf_s, fwscanf_s, swscanf_s

From cppreference.net
< c ‎ | io
C
File input/output
Types and objects
Functions
File access
Unformatted input/output
Formatted input
(C11) (C11) (C11)
wscanf fwscanf swscanf wscanf_s fwscanf_s swscanf_s
(C95) (C95) (C95) (C11) (C11) (C11)
定义于头文件 <wchar.h>
(1)
int wscanf ( const wchar_t * format, ... ) ;
(C95起)
(C99前)
int wscanf ( const wchar_t * restrict format, ... ) ;
(C99起)
(2)
int fwscanf ( FILE * stream, const wchar_t * format, ... ) ;
(C95起)
(C99前)
int fwscanf ( FILE * restrict stream,
const wchar_t * restrict format, ... ) ;
(C99起)
(3)
int swscanf ( const wchar_t * buffer, const wchar_t * format, ... ) ;
(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_t 的值，指示接收数组的大小，当使用 % lc 读取单个宽字符时该值可为 1 ），并且以下错误会在运行时被检测到并调用当前安装的 约束处理函数 ：
  • 任何指针类型的参数是空指针
  • format 、 stream 或 buffer 是空指针
  • 通过 % c 、 % s 或 % [ 写入的字符数（加上终止空字符）将超过为这些转换说明符提供的第二个（ rsize_t ）参数
  • 可选地，任何其他可检测错误，例如未知转换说明符
与所有边界检查函数一样，仅当实现定义了 __STDC_LIB_EXT1__ 且用户在包含 <wchar.h> 之前将 __STDC_WANT_LIB_EXT1__ 定义为整型常量 1 时，才保证 wscanf_s 、 fwscanf_s 和 swscanf_s 可用。

目录

参数

stream - 用于读取的输入文件流
buffer - 指向以空字符结尾的宽字符串的指针，用于读取数据
format - 指向以空字符结尾的宽字符串的指针，指定输入读取格式
... - 接收参数


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

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

以下格式说明符可用：

转换
说明符 		说明 期望
参数类型
长度修饰符→ hh h 无 l ll j z t L
仅自 C99 起可用→ 是 是 是 是 是
%
匹配字面量 % 。
N/A N/A N/A N/A N/A N/A N/A N/A N/A
c

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

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

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

  • 若使用宽度限定符，则最多匹配 width 个字符或遇到首个空白字符即停止（以先到者为准）。
  • 始终在匹配字符后存储空字符（因此参数数组必须至少有 width+1 个字符的空间）。
[ set  ]

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

  • 若字符集的首字符为 ^ ，则匹配所有不在该集合中的字符。
  • 若字符集以 ] 或 ^] 开头，则 ] 字符也会被包含在集合中。
  • 在非起始位置出现的 - 字符是否表示范围（如 [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 *
不适用
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 之外的所有转换说明符，从流中消耗的输入字符序列是：不超过指定字段宽度、且完全符合转换说明符预期或为其预期序列前缀的最长字符序列。该消耗序列后的首个字符（若存在）将保持未读取状态。若消耗序列长度为零，或消耗序列无法按上述规则转换，则出现匹配失败——除非因文件终止、编码错误或读取错误导致无法从流中获取输入，此时属于输入失败。

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

若未使用长度说明符 l ，则转换说明符 c 、 s 和 [ 会执行宽字符到多字节字符的转换，其过程类似于在转换首个字符前调用 wcrtomb ，且 mbstate_t 对象被初始化为零。

转换说明符 s 和 [ 除了存储匹配的字符外，始终会存储空终止符。目标数组的大小必须至少比指定字段宽度大1。若使用 % s 或 % [ 时未指定目标数组大小，其不安全性等同于 gets 。

固定宽度整数类型 （如 int8_t 等）的正确转换规范定义在头文件 <inttypes.h> 中（尽管 SCNdMAX 、 SCNuMAX 等分别等同于 % jd 、 % ju 等）。

每个转换说明符执行完毕后存在一个 顺序点 ，这允许将多个字段存储至同一个“接收”变量中。

当解析以指数符号结尾但无数字的不完整浮点数值时（例如使用转换说明符 % f 解析 "100er" ），会消耗序列 "100e" （可能有效的浮点数的最长前缀），导致匹配错误（消耗的序列无法转换为浮点数），并保留 "r" 。部分现有实现未遵循此规则，会回退至仅消耗 "100" ，留下 "er" ，例如 glibc bug 1765 。

若转换规范无效，则行为未定义。

返回值

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

示例

运行此代码 
#include <stdio.h>
#include <wchar.h>
#include <string.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"输入州名、年龄和pi值: ");
    if (wscanf(L"%ls%d%f", state, &age, &pi) != NUM_VARS) {
        fprintf(stderr, "读取输入时出错。\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, "读取输入时出错。\n");
        return ERR_READ;
    }
#endif
    wprintf(L"州名: %ls\n年龄  : %d 年\nPi   : %.5f\n\n", state, age, pi);
    FILE* fp = tmpfile();
    if (fp) {
        // 向临时文件写入数据
        if (!fwprintf(fp, L"Mississippi Jackson 420000 807")) {
            fprintf(stderr, "写入文件时出错。\n");
            fclose(fp);
            return ERR_WRITE;
        }
        // 重置文件指针
        rewind(fp);
        // 将数据读入变量
        fwscanf(fp, L"%ls%ls%u%d", state, capital, &population, &elevation);
        wprintf(L"州名  : %ls\n首府: %ls\n杰克逊人口（2020年）: %u\n"
                L"最高海拔: %d英尺\n",
                state, capital, population, elevation);
        fclose(fp);
    }
}

可能的输出： 

州名: California
年龄  : 170 年
Pi   : 3.14159
州名  : Mississippi
首府: Jackson
杰克逊人口（2020年）: 420000
最高海拔: 807英尺

参考文献

  • 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