命名空间
变体
操作

wscanf、fwscanf、swscanf、wscanf_s、fwscanf_s、swscanf_s

来自 cppreference.com
< c‎ | io
 
C
 
文件输入/输出
类型和对象
函数
文件访问
直接输入/输出
非格式化输入/输出
(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) 从以 null 结尾的宽字符串 buffer 读取数据。到达字符串末尾等效于对 fwscanf 达到文件末尾条件。
4-6) 与 (1-3) 相同，不同之处在于 %c、%s 和 %[ 转换说明符分别期望两个参数（通常的指针和类型为 rsize_t 的值，表示接收数组的大小，当使用 %lc 将数据读入单个宽字符时，该值可以为 1），不同之处还在于以下错误会在运行时被检测到，并调用当前已安装的 约束处理程序 函数
  • 任何指针类型的参数都是空指针
  • format、stream 或 buffer 是空指针
  • 由 %c、%s 或 %[ 写入的字符数加上终止 null 字符，将超过为每个这些转换说明符提供的第二个（rsize_t）参数
  • 或者，任何其他可检测到的错误，例如未知的转换说明符
与所有边界检查函数一样，wscanf_s、fwscanf_s 和 swscanf_s 仅在实现定义了 __STDC_LIB_EXT1__，并且用户在包含 <wchar.h> 之前将 __STDC_WANT_LIB_EXT1__ 定义为整型常量 1 的情况下才保证可用。

内容

[编辑] 参数

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


format 字符串由以下内容组成

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

以下格式说明符可用

转换
说明符		 解释 参数类型
长度修饰符 →
 hh

(C99)

h (无) l ll

(C99)

j

(C99)

z

(C99)

t

(C99)

L
% 匹配文字 %。 N/A N/A N/A N/A N/A N/A N/A N/A N/A
c
匹配一个字符或一系列字符。

如果使用宽度说明符，则匹配恰好宽度个宽字符（参数必须是指向具有足够空间的数组的指针）。与 %s 和 %[ 不同，它不会将 null 字符追加到数组中。

 N/A N/A
char*
wchar_t*
 N/A N/A N/A N/A N/A
s
匹配非空白字符序列（一个 **字符串**）。

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

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

如果集合的第一个字符是 ^，则匹配集合中没有的字符。如果集合以 ] 或 ^] 开头，则 ] 字符也被包含在集合中。是否在扫描集的非初始位置的字符 - 表示一个范围，如 [0-9]，是实现定义的。如果使用宽度说明符，则只匹配最多 宽度 个字符。始终存储一个空字符，除了匹配的字符（因此参数数组必须至少有 宽度+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, 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 和 [ 始终存储空终止符，除了匹配的字符之外。目标数组的大小必须至少比指定的字段宽度大 1。使用 %s 或 %[，而不指定目标数组的大小，与 gets 一样不安全。

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

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

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

[edit] 返回值

1-3) 成功分配的接收参数数量，或 EOF，如果在第一个接收参数被分配之前发生读取失败。
4-6) 与 (1-3) 相同，只是 EOF 也会在发生运行时约束冲突时返回。

[edit] 示例

运行此代码
#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

[edit] 参考资料

  • 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)

[edit] 另请参阅

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