命名空间
变体
操作

wscanf, fwscanf, swscanf, wscanf_s, fwscanf_s, swscanf_s

来自 cppreference.cn
< c‎ | io
 
C
 
文件输入/输出
类型和对象
        
函数
文件访问
(C11)
(C11)  
(C95)
非格式化输入/输出
(C95)(C95)
(C95)
(C95)(C95)
(C95)
(C95)
(C95)
(C95)

格式化输入
(C11)(C11)(C11)
wscanffwscanfswscanfwscanf_sfwscanf_sswscanf_s
(C95)(C95)(C95)(C11)(C11)(C11)
(C99)(C99)(C99)(C11)(C11)(C11)
(C99)(C99)(C99)(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

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

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

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

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

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

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

匹配一个十进制整数。

  • 数字格式与 wcstol 期望的格式相同，`base` 参数的值为 10。
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

匹配一个整数。

  • 数字格式与 wcstol 期望的格式相同，`base` 参数的值为 ​0​（基数由解析的第一个字符确定）。
u

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

  • 数字格式与 wcstoul 期望的格式相同，`base` 参数的值为 10。
o

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

  • 数字格式与 wcstoul 期望的格式相同，`base` 参数的值为 8。
x
X

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

  • 数字格式与 wcstoul 期望的格式相同，`base` 参数的值为 16。
n

返回目前读取的字符数。

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

匹配一个浮点数。

  • 数字格式与 wcstof 期望的格式相同。
 N/A N/A
float*
double*
 N/A N/A N/A N/A
long double*
p

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

  • `printf` 函数族应使用 `%p` 格式说明符生成相同的序列。
 N/A N/A
void**
 N/A N/A N/A N/A N/A N/A
注意

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

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

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

转换说明符 s 和 [ 除了匹配的字符外，总是存储空终止符。目标数组的大小必须至少比指定的字段宽度大一。使用 %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"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

[编辑] 参考

  • C11 标准 (ISO/IEC 9899:2011)
  • 7.29.2.2 fwscanf 函数 (p: 410-416)
  • 7.29.2.4 swscanf 函数 (p: 417)
  • 7.29.2.12 wscanf 函数 (p: 421)
  • K.3.9.1.2 fwscanf_s 函数 (p: 628-629)
  • K.3.9.1.5 swscanf_s 函数 (p: 631)
  • K.3.9.1.14 wscanf_s 函数 (p: 638)
  • C99 标准 (ISO/IEC 9899:1999)
  • 7.24.2.2 fwscanf 函数 (p: 356-362)
  • 7.24.2.4 swscanf 函数 (p: 362)
  • 7.24.2.12 wscanf 函数 (p: 366-367)

[编辑] 另请参阅

(C99)(C99)(C99)(C11)(C11)(C11)
 从 stdin、文件流读取格式化的宽字符输入
或使用可变参数列表的缓冲区
(函数) [编辑]
wscanf, fwscanf, swscanf 的C++ 文档
取自 "https://cppreference.cn/mwiki/index.php?title=c/io/fwscanf&oldid=140800"