名稱空間
變體
操作

wscanf, fwscanf, swscanf, wscanf_s, fwscanf_s, swscanf_s

來自 cppreference.com
< 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.tw/mwiki/index.php?title=c/io/fwscanf&oldid=140800"