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

 

C++

編譯器支援

自由（freestanding）與宿主（hosted）

語言

標準庫

標準庫標頭檔案

具名要求

特性測試宏 (C++20)

語言支援庫

概念庫 (C++20)

診斷庫

記憶體管理庫

超程式設計庫 (C++11)

通用工具庫

容器庫

迭代器庫

範圍庫 (C++20)

演算法庫

字串庫

文字處理庫

數值庫

日期和時間庫

輸入/輸出庫

檔案系統庫 (C++17)

併發支援庫 (C++11)

執行控制庫 (C++26)

技術規範

符號索引

外部庫

 

輸入/輸出庫

I/O 操縱器

列印函式 (C++23)

C 風格 I/O

緩衝區

basic_streambuf

basic_filebuf

basic_stringbuf

basic_spanbuf (C++23)

strstreambuf (C++98/26*)

basic_syncbuf (C++20)

流

抽象

ios_base

basic_ios

basic_istream

basic_ostream

basic_iostream

檔案 I/O

basic_ifstream

basic_ofstream

basic_fstream

字串 I/O

basic_istringstream

basic_ostringstream

basic_stringstream

陣列 I/O

basic_ispanstream (C++23)

basic_ospanstream (C++23)

basic_spanstream (C++23)

istrstream (C++98/26*)

ostrstream (C++98/26*)

strstream (C++98/26*)

同步輸出

basic_osyncstream (C++20)

型別

streamoff

streamsize

fpos

錯誤類別介面

iostream_category (C++11)

io_errc (C++11)

 

C 風格 I/O

型別和物件
FILE fpos_t	stdinstdoutstderr
函式
檔案訪問 fopen freopen fclose fflush fwide setbuf setvbuf 直接輸入/輸出 fread fwrite 非格式化輸入/輸出 fgetcgetc fgets fputcputc fputs getchar gets (直到 C++14) putchar puts ungetc fgetwcgetwc fgetws fputwcputwc fputws getwchar putwchar ungetwc 格式化輸入 scanffscanfsscanf vscanfvfscanfvsscanf (C++11 起)(C++11 起)(C++11 起)     wscanffwscanfswscanf vwscanfvfwscanfvswscanf (C++11 起)(C++11 起)(C++11 起)	格式化輸出 printffprintfsprintfsnprintf (C++11 起) vprintfvfprintfvsprintfvsnprintf (C++11 起)     wprintffwprintfswprintf vwprintfvfwprintfvswprintf 檔案定位 ftell fgetpos fseek fsetpos rewind 錯誤處理 clearerr feof ferror perror 檔案操作 remove rename tmpfile tmpnam

 

定義於標頭檔案 <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 ]	匹配來自字元 set 的非空字元序列。 如果集合的第一個字元是 `^`，則匹配集合中不包含的所有字元。 如果集合以 `]` 或 `^]` 開頭，則 `]` 字元也包含在集合中。 在掃描集中非起始位置的字元 `-` 是否表示範圍（如 `[0-9]`）是實現定義的。 如果使用寬度說明符，則只匹配最多 *width* 個字元。 除了匹配的字元外，始終儲存一個空字元（因此引數陣列必須至少有 *width+1* 個字元的空間）。
d	匹配一個十進位制整數。 數字格式與 std::strtol 期望的相同，其中 base 引數的值為 10。	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*	不適用
i	匹配一個整數。 數字格式與 std::strtol 期望的相同，其中 base 引數的值為 ​0​（基數由解析的第一個字元確定）。
u	匹配一個無符號十進位制整數。 數字格式與 std::strtoul 期望的相同，其中 base 引數的值為 10。
o	匹配一個無符號八進位制整數。 數字格式與 std::strtoul 期望的相同，其中 base 引數的值為 8。
x X	匹配一個無符號十六進位制整數。 數字格式與 std::strtoul 期望的相同，其中 base 引數的值為 16。
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 之外的每個轉換說明符，從流中消耗的輸入字元序列最長，且不超過任何指定的欄位寬度，並且要麼與轉換說明符期望的完全相同，要麼是其期望序列的字首。如果存在，此消耗序列之後的第一個字元仍未讀取。如果消耗的序列長度為零，或者如果消耗的序列無法按上述方式轉換，則發生匹配失敗，除非檔案結束、編碼錯誤或讀取錯誤阻止了流輸入，在這種情況下是輸入失敗。 除了 [、c 和 n 之外的所有轉換說明符，在嘗試解析輸入之前，會消耗並丟棄所有前導空白字元（透過呼叫 std::isspace 確定）。這些消耗的字元不計入指定的最大欄位寬度。 轉換說明符 lc、ls 和 l[ 執行多位元組到寬字元的轉換，如同在轉換第一個字元之前，透過呼叫 std::mbrtowc 並使用初始化為零的 std::mbstate_t 物件一樣。 轉換說明符 s 和 [ 除了匹配的字元外，總是儲存空終止符。目標陣列的大小必須至少比指定的欄位寬度大一。在不指定目標陣列大小的情況下使用 %s 或 %[，與使用 std::gets 一樣不安全。 固定寬度整數型別（std::int8_t 等）的正確轉換規範定義在標頭檔案 <cinttypes> 中（儘管 SCNdMAX、SCNuMAX 等與 %jd、%ju 等同義）。 在每個轉換說明符的操作之後都有一個序列點；這允許在同一個“接收器”變數中儲存多個欄位。 當解析不完整的浮點值，該值以指數結尾但沒有數字時，例如使用轉換說明符 %f 解析 "100er"，序列 "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

參閱

scanffscanfsscanf	從 stdin、檔案流或緩衝區讀取格式化輸入 (函式)
vprintfvfprintfvsprintfvsnprintf (C++11 起)	將格式化輸出列印到 stdout、檔案流或緩衝區 使用可變引數列表 (函式)
C 文件 適用於 vscanf, vfscanf, vsscanf