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 、および % [ 変換指定子がそれぞれ2つの引数を期待する点（通常のポインタと、受信配列のサイズを示す rsize_t 型の値。単一のワイド文字に % lc で読み込む場合は 1 となる）と、以下のエラーが実行時に検出され、現在インストールされている 制約ハンドラ 関数を呼び出す点が異なる：
  • ポインタ型の引数のいずれかがnullポインタである場合
  • format 、 stream または buffer がnullポインタである場合
  • % c 、 % s 、または % [ によって書き込まれる文字数（終端のnull文字を含む）が、各変換指定子に提供された2番目（ rsize_t ）の引数を超える場合
  • オプションで、未知の変換指定子などの他の検出可能なエラー
すべての境界チェック付き関数と同様に、 wscanf_s 、 fwscanf_s 、および swscanf_s は、実装によって __STDC_LIB_EXT1__ が定義され、かつユーザーが <wchar.h> をインクルードする前に __STDC_WANT_LIB_EXT1__ を整数定数 1 に定義した場合にのみ利用可能であることが保証される。

目次

パラメータ

stream - 読み取り元の入力ファイルストリーム
buffer - 読み取り元のヌル終端ワイド文字列へのポインタ
format - 入力の読み取り方法を指定するヌル終端ワイド文字列へのポインタ
... - 受信引数


format 文字列は以下で構成されます

  • 空白文字以外のワイド文字（ % を除く）：書式文字列内の各文字は、入力ストリームから正確に同一の文字1文字を消費する。ストリーム上の次の文字が等しくない場合、関数は失敗する。
  • 空白文字：書式文字列内の単一の空白文字は、入力から利用可能な連続する全ての空白文字を消費する（ループで 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

1文字または文字のシーケンスにマッチします。

  • 幅指定子が使用される場合、正確に width 個のワイド文字にマッチします（引数は十分な領域を持つ配列へのポインタでなければなりません）。
  • %sや%[とは異なり、配列にnull文字を追加しません。
N/A N/A
char *
wchar_t *
N/A N/A N/A N/A N/A
s

空白以外の文字の連続（ 文字列 ）にマッチします。

  • 幅指定子が使用されている場合、 width まで、または最初の空白文字のいずれか先に現れる方にマッチします。
  • 常にマッチした文字に加えてヌル文字を格納します（そのため、引数の配列には少なくとも width+1 文字分の領域が必要です）。
[ set  ]

set 内の文字からなる空でない文字シーケンスにマッチします。

  • セットの最初の文字が ^ の場合、セットに含まれないすべての文字がマッチします。
  • セットが ] または ^] で始まる場合、 ] 文字もセットに含まれます。
  • スキャンセット内の先頭以外の位置にある - 文字が [0-9] のように範囲を示すかどうかは実装定義です。
  • 幅指定子が使用されている場合、最大 width 文字までマッチします。
  • 常にマッチした文字に加えてnull文字を格納します（したがって、引数配列には少なくとも width+1 文字分の領域が必要です）。
d

10進整数 にマッチします。

  • 数値の形式は、 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

符号なし 10進整数 にマッチします。

  • 数値の形式は、 wcstoul 関数が 10 を base 引数として期待する形式と同じです。
o

符号なし 8進整数 にマッチします。

  • 数値の形式は、 wcstoul 関数が 8 を base 引数として期待する形式と同じです。
x
X

符号なし 16進整数 にマッチします。

  • 数値のフォーマットは、 wcstoul 関数が 16 を base 引数として期待するものと同じです。
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 、 [ は、最初の文字が変換される前にゼロに初期化された mbstate_t オブジェクトを使用して wcrtomb を呼び出した場合と同様に、ワイド文字からマルチバイト文字への変換を実行します。

変換指定子 s と [ は、常に一致した文字に加えてナルターミネータを格納します。変換先配列のサイズは、指定されたフィールド幅より少なくとも1以上大きくなければなりません。変換先配列のサイズを指定せずに % s または % [ を使用することは、 gets と同様に安全ではありません。

固定幅整数型 （ int8_t など）に対する正しい変換指定はヘッダ <inttypes.h> で定義されています（ただし SCNdMAX 、 SCNuMAX などは % jd 、 % ju などのシノニムです）。

各変換指定子の動作後に シーケンスポイント が存在します。これにより、複数のフィールドを同じ「シンク」変数に格納することが可能になります。

指数部で終わる不完全な浮動小数点値（例えば "100er" を変換指定子 % f で解析する場合）を解析する際、 "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) {
        // 一時ファイルにデータを書き込む
        if (!fwprintf(fp, L"Mississippi Jackson 420000 807")) {
            fprintf(stderr, "Error writing to file.\n");
            fclose(fp);
            return ERR_WRITE;
        }
        // ファイルポインタを巻き戻す
        rewind(fp);
        // データを変数に読み込む
        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 、ファイルストリーム
またはバッファからフォーマットされたワイド文字入力を読み取る
(関数)
C++ドキュメント for wscanf , fwscanf , swscanf