名前空間
変種
操作

wscanf, fwscanf, swscanf, wscanf_s, fwscanf_s, swscanf_s

提供: cppreference.com
< c‎ | io
 
 
ファイル入出力
関数
ファイルアクセス
直接入出力
書式なし入出力
(C11以前)(C11およびそれ以降)
(C95)(C95)
(C95)
(C95)(C95)
(C95)
(C95)
書式付き入力
wscanffwscanfswscanfwscanf_sfwscanf_sswscanf_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 型の値 (%c で単一の文字を読み込むときは 1 になるかもしれません)) を期待し、以下のエラーを実行時に検出して現在設定されている制約ハンドラ関数を呼びます。
  • ポインタ型の引数のいずれかがヌルポインタ。
  • formatstream または buffer がヌルポインタ。
  •  %c、 %s または %[ によって書き込まれるであろう文字数プラス終端のヌル文字が、それらの変換指定子に対して提供された2番目の (rsize_t 型の) 引数を超える。
  • オプションで、不明な変換指定子などのその他の検出可能なあらゆるエラー。
すべての境界チェック付き関数と同様に、 wscanf_sfwscanf_s、 および swscanf_s__STDC_LIB_EXT1__ が処理系によって定義されていて、 <wchar.h> をインクルードする前にユーザが __STDC_WANT_LIB_EXT1__ を整数定数 1 に定義した場合にのみ、利用可能であることが保証されます。

目次

[編集] 引数

stream - 読み込む入力ファイルストリーム
buffer - 読み込むヌル終端ワイド文字列を指すポインタ
format - 入力の読み込み方法を指定するヌル終端ワイド文字列を指すポインタ。

書式文字列は以下から構成されます。

  • % を除く非ホワイトスペースワイド文字。 書式文字列内のそのような文字はそれぞれ、入力ストリームから正確に同一の文字をひとつ消費します。 または、ストリームの次の文字が等しくなければ、関数を失敗させます。
  • ホワイトスペース文字。 書式文字列内のあらゆる単一のホワイトスペース文字は、入力から利用可能な連続するすべてのホワイトスペース文字を消費します (iswspace を繰り返し呼んだかのように判定されます)。 書式文字列内の "\n"" ""\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 および %[ と異なり、配列にヌル文字を追加しません。

N/A N/A
char*
wchar_t*
N/A N/A N/A N/A N/A
s

非ホワイトスペース文字の並び (文字列) にマッチします。

幅指定子が使用されている場合は、最大 個の文字または最初のホワイトスペース文字どちらか先に現れたところまでマッチします。 マッチした文字に加えて必ずヌル文字が格納されます (そのため引数の配列は少なくとも文字 幅+1 個分の空間を持っていなければなりません)。

[set]

set 内の文字の空でない並びにマッチします。

set の最初の文字が ^ の場合は、 set 内に無いすべての文字がマッチします。 set が ] または ^] で始まる場合は、 ] 文字も set 内に含まれます。 [0-9] のような、 set 内の先頭でない位置にある文字 - が範囲を表すかどうかは、処理系定義です。 幅指定子が使用されている場合は、最大 個の文字にのみマッチします。 マッチした文字に加えて必ずヌル文字が格納されます (そのため引数の配列は少なくとも文字 幅+1 個分の空間を持っていなければなりません)。

d

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

数値の書式は base 引数に値 10 を指定した wcstol() が期待するものと同じです。

signed char* または unsigned char*
signed short* または unsigned short*
signed int* または unsigned int*
signed long* または unsigned long*
signed long long* または unsigned long long*
intmax_t* または uintmax_t*
N/A
i

整数にマッチします。

数値の書式は base 引数に値 0 を指定した wcstol() が期待するものと同じです (基数はパースされる最初の文字によって決定されます)。

u

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

数値の書式は base 引数に値 10 を指定した wcstoul() が期待するものと同じです。

o

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

数値の書式は base 引数に値 8 を指定した wcstoul() が期待するものと同じです。

x, X

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

数値の書式は base 引数に値 16 を指定した wcstoul() が期待するものと同じです。

n

それまでに読み込んだ文字数を返します。

入力は消費されません。 代入カウントをインクリメントしません。 指定子が代入抑制文字を持っている場合、動作は未定義です。

a, A(C99)
e, E
f, F
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 が使用されていない場合、変換指定子 cs および [ は、最初の文字が変換される前に、ゼロに初期化された mbstate_t オブジェクトを使用して wcrtomb() を呼んだかのように、ワイド文字からマルチバイト文字への変換を行います。

変換指定子 s および [ はマッチした文字に加えて必ずヌル終端を格納します。 格納先の配列のサイズは指定されたフィールド幅よりも少なくとも1文字多くなければなりません。 格納先の配列のサイズを指定せずに %s または %[ を使用することは、 gets と同様に、安全ではありません。

固定幅の整数型に対する正しい変換仕様は、ヘッダ <inttypes.h> で定義されています (SCNdMAX, SCNuMAX などは %jd, %ju などの同義語ですが)。

変換指定子それぞれの動作後に副作用完了点があります。 これにより同じ「ゴミ箱」変数に複数のフィールドを格納することができます。

数字のない指数で終わる不完全な浮動小数点値をパースするとき、例えば変換指定子 %f"100er" をパースするとき、シーケンス "100e" (有効な浮動小数点数の可能性がある最も長い接頭辞) が消費され、結果はマッチエラーとなり (消費したシーケンスは浮動小数点数に変換できません)、 "r" が残されます。 処理系によってはこのルールに従わず、ロールバックして "100" のみを消費し、 "er" を残します (glibc bug 1765)。 書式文字列は以下から構成されます。

  • % を除く非ホワイトスペースワイド文字。 書式文字列内のそのような文字はそれぞれ、入力ストリームから正確に同一の文字をひとつ消費します。 または、ストリームの次の文字が等しくなければ、関数を失敗させます。
  • ホワイトスペース文字。 書式文字列内のあらゆる単一のホワイトスペース文字は、入力から利用可能な連続するすべてのホワイトスペース文字を消費します (iswspace を繰り返し呼んだかのように判定されます)。 書式文字列内の "\n"" ""\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 および %[ と異なり、配列にヌル文字を追加しません。

N/A N/A
char*
wchar_t*
N/A N/A N/A N/A N/A
s

非ホワイトスペース文字の並び (文字列) にマッチします。

幅指定子が使用されている場合は、最大 個の文字または最初のホワイトスペース文字どちらか先に現れたところまでマッチします。 マッチした文字に加えて必ずヌル文字が格納されます (そのため引数の配列は少なくとも文字 幅+1 個分の空間を持っていなければなりません)。

[set]

set 内の文字の空でない並びにマッチします。

set の最初の文字が ^ の場合は、 set 内に無いすべての文字がマッチします。 set が ] または ^] で始まる場合は、 ] 文字も set 内に含まれます。 [0-9] のような、 set 内の先頭でない位置にある文字 - が範囲を表すかどうかは、処理系定義です。 幅指定子が使用されている場合は、最大 個の文字にのみマッチします。 マッチした文字に加えて必ずヌル文字が格納されます (そのため引数の配列は少なくとも文字 幅+1 個分の空間を持っていなければなりません)。

d

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

数値の書式は base 引数に値 10 を指定した wcstol() が期待するものと同じです。

signed char* または unsigned char*
signed short* または unsigned short*
signed int* または unsigned int*
signed long* または unsigned long*
signed long long* または unsigned long long*
intmax_t* または uintmax_t*
N/A
i

整数にマッチします。

数値の書式は base 引数に値 0 を指定した wcstol() が期待するものと同じです (基数はパースされる最初の文字によって決定されます)。

u

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

数値の書式は base 引数に値 10 を指定した wcstoul() が期待するものと同じです。

o

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

数値の書式は base 引数に値 8 を指定した wcstoul() が期待するものと同じです。

x, X

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

数値の書式は base 引数に値 16 を指定した wcstoul() が期待するものと同じです。

n

それまでに読み込んだ文字数を返します。

入力は消費されません。 代入カウントをインクリメントしません。 指定子が代入抑制文字を持っている場合、動作は未定義です。

a, A(C99)
e, E
f, F
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 が使用されていない場合、変換指定子 cs および [ は、最初の文字が変換される前に、ゼロに初期化された mbstate_t オブジェクトを使用して wcrtomb() を呼んだかのように、ワイド文字からマルチバイト文字への変換を行います。

変換指定子 s および [ はマッチした文字に加えて必ずヌル終端を格納します。 格納先の配列のサイズは指定されたフィールド幅よりも少なくとも1文字多くなければなりません。 格納先の配列のサイズを指定せずに %s または %[ を使用することは、 gets と同様に、安全ではありません。

固定幅の整数型に対する正しい変換仕様は、ヘッダ <inttypes.h> で定義されています (SCNdMAX, SCNuMAX などは %jd, %ju などの同義語ですが)。

変換指定子それぞれの動作後に副作用完了点があります。 これにより同じ「ゴミ箱」変数に複数のフィールドを格納することができます。

数字のない指数で終わる不完全な浮動小数点値をパースするとき、例えば変換指定子 %f"100er" をパースするとき、シーケンス "100e" (有効な浮動小数点数の可能性がある最も長い接頭辞) が消費され、結果はマッチエラーとなり (消費したシーケンスは浮動小数点数に変換できません)、 "r" が残されます。 処理系によってはこのルールに従わず、ロールバックして "100" のみを消費し、 "er" を残します (glibc bug 1765)。


... - 受け取り引数

[編集] 戻り値

1-3) 読み込みに成功した引数の数、または最初の受け取り引数が代入される前に失敗が発生した場合は EOF
4-6) (1-3) と同じですが、実行時制約違反があった場合も EOF が返されます。

[編集]

[編集] 参考文献

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

[編集] 関連項目

stdin、ファイルストリームまたはバッファから可変個引数リストを使用して書式付きワイド文字入力を読み取ります
(関数) [edit]
wscanf, fwscanf, swscanfC++リファレンス