名称

wscanf, fwscanf, swscanf, vwscanf, vswscanf, vfwscanf — ワイド文字入力形式変換

ライブラリ

Standard C Library (libc, -lc)

書式

#include < stdio.h>
#include < wchar.h>

int
wscanf( const wchar_t * restrict format, ...);

int
fwscanf( FILE * restrict stream, const wchar_t * restrict format, ...);

int
swscanf( const wchar_t * restrict str, const wchar_t * restrict format, ...);

#include < stdarg.h>

int
vwscanf( const wchar_t * restrict format, va_list ap);

int
vswscanf( const wchar_t * restrict str, const wchar_t * restrict format, va_list ap);

int
vfwscanf( FILE * restrict stream, const wchar_t * restrict format, va_list ap);

解説

wscanf() 関数ファミリは以下で説明されるように format に従って入力をスキャンします。この形式 (format) は、 変換指定子 含みます。そのような変換の結果は、もしあれば、 pointer 引数を通して格納されます。 wscanf() 関数は標準入力ストリーム stdin から入力を読み込み、 fwscanf() はストリームポインタ stream から入力を読み込み、そして swscanf() は str によって指されたワイド文字列の入力を読み込みます。 vfwscanf() 関数は vfwprintf(3) 類似して、ポインタの可変引数リスト ( stdarg(3) 参照) を使用して、ストリームポインタ stream の入力を読み込みます。 vwscanf() 関数は標準入力から可変引数リストをスキャンし、 vswscanf() 関数はワイド文字列からそれをスキャンします。これらはそれぞれ vwprintf() と vswprintf() 関数に類似しています。それぞれの連続した pointer 引数はそれぞれの連続した変換指定子 (下記の * 変換を参照) に適切に対応しなければなりません。すべての変換は % (パーセント記号) 文字によって導入されます。また、 format 文字列は他の文字を含むことができます。 format 文字列中の (空白、タブ、または改行などの) 空白類は入力でなにも含んでいない、いくつかの空白類に適合します。ほかのすべてはそれ自体にだけ適合します。入力文字がそのような形式の文字に適合しないとき、スキャンは止まります。また、入力変換を行うことができないときも (下記参照)、スキャンは止まります。

変換

% 文字で導入される変換に続いて、次のように、多くの flag 文字を指定できます:

*

割り当てを抑圧します。続く変換はいつものように起こりますが、ポインタは使用されません。変換の結果は単に捨てられます。

hh

変換が dioux か n の 1 つであり、次のポインタが ( int ではなく) char へのポインタであることを示します。

h

変換が dioux か n の 1 つであり、次のポインタが ( int ではなく) short int へのポインタであることを示します。

l (エル)

変換が dioux か n の 1 つであり、次のポインタが ( int ではなく) long int へのポインタである、変換が a, e, f, か g の 1 つであり、次のポインタが ( float ではなく) double へのポインタである、または変換が c か s の 1 つであり、次のポインタが ( char ではなく) wchar_t の配列へのポインタであることを示します。

ll (エルエル)

変換が dioux か n の 1 つであり、次のポインタが ( int ではなく) long long int へのポインタであることを示します。

L

変換が a, e, f か g の 1 つであり、次のポインタが long double へのポインタであることを示します。

j

変換が dioux か n の 1 つであり、次のポインタが ( int ではなく) intmax_t へのポインタであることを示します。

t

変換が dioux か n の 1 つであり、次のポインタが ( int ではなく) ptrdiff_t へのポインタであることを示します。

z

変換が dioux か n の 1 つであり、次のポインタが ( int ではなく) size_t へのポインタであることを示します。

q

(非推奨。) 変換が dioux か n の 1 つであり、次のポインタが ( int ではなく) long long int へのポインタであることを示します。

これらのフラグに加えて、 % と変換文字の間には 10 進整数で表現される省略可能な最大のフィールド幅があります。幅が与えられないなら、“無限 (infinity)”のデフォルトが使用されます (下記に、ただ 1 つの例外があります)。そうでなければ、多くてもこんなにたくさんの文字が変換の処理でスキャンされます。変換が始まる前に、ほとんどの変換文字は空白類をスキップします。この空白類はフィールドの幅に対して数えられません。

次の変換文字が利用可能です:

%

文字‘ %’に適合します。すなわち、format 文字列中の“ %%”は単一の入力‘ %’文字に適合します。変換は全く行われません、そして、代入は起こりません。

d

符号が省略可能な 10 進整数に適合します。次のポインタは int へのポインタでなければなりません。

i

符号が省略可能な整数に適合します。次のポインタは int へのポインタでなければなりません。整数は‘ 0x’または‘ 0X’で始まれば、16 進で、‘ 0’で始まれば、8 進で、そうでなければ 10 進で読み込まれます。ベース (進) に対応する文字だけが使用されます。

o

8 進整数に適合します。次のポインタは unsigned int へのポインタでなければなりません。

u

符号が省略可能な 10 進整数に適合します。次のポインタは unsigned int へのポインタでなければなりません。

x, X

符号が省略可能な 16 進整数に適合します。次のポインタは unsigned int へのポインタでなければなりません。

a, A, e, E, f, F, g, G

wcstod(3) スタイルの浮動小数点数に適合します。次のポインタは float ( l か L が指定されない場合) へのポインタでなければなりません。

s

空白類でないワイド文字のシーケンスに適合します。次のポインタは char へのポインタでなければなりません、そして、配列はすべてのシーケンスのマルチバイト表現と終端の ヌル 文字を受け付けることができるくらい大きくなければなりません。入力文字列は空白類、または最大のフィールド幅のいずれかが最初に起こるなら止まります。

l 修飾子が存在するなら、次のポインタは、入力が置かれる、 wchar_t へのポインタでなければなりません。

S

ls と同じです。

c

width カウントのワイド文字 (デフォルト 1) のシーケンスに適合します。次のポインタは char へのポインタでなければなりません、そして、すべての文字のマルチバイト表現ために十分な空間がなければなりません (終端の ヌル 文字は追加されません)。通常の先導する空白類のスキップは抑圧されます。最初に空白類をスキップするためには、format 中に明白な空白を使用します。

l 修飾子が存在するなら、次のポインタは、入力が置かれる、 wchar_t へのポインタでなければなりません。

C

lc と同じです。

[

特定の受け付けられた文字の集合から文字の空でないシーケンスに適合します。次のポインタは char へのポインタでなければなりません、そして、文字列中のすべての文字のマルチバイト表現、と終端の ヌル 文字のために十分な空間がなければなりません。通常の先導する空白類のスキップは抑圧されます。文字列は特定の集合中 (または集合でない) の文字で構成されています。集合は開き角括弧 [ 文字と閉じ角括弧 ] 文字の間の文字によって定義されます。集合は開き角括弧の後の最初の文字がサーカムフレックス ^ であるなら、それらの文字を 除きます。集合に閉じ角括弧を含めるためには、開き角括弧かサーカムフレックスの後の最初の文字にしてください。その他の位置は集合を終わらせます。集合にハイフンを含めるためには、最終の閉じ角括弧の前でそれを最後の文字にします。 wscanf() のいくつかの実装は、‘ A’と‘ Z’の間の文字範囲を表現するために“ A-Z”を使用します。文字列は集合 (または、サーカムフレックス) 中にない文字の出現、またはフールドの幅を使い果たして終ります。

l 修飾子が存在するなら、次のポインタは、入力が置かれる、 wchar_t へのポインタでなければなりません。

p

( wprintf(3) の‘ %p’で印刷されるような) ポインタ値に適合します。次のポインタは void へのポインタでなければなりません。

n

何も予期されません。代わりに、入力からここまで消費された文字の数が、次のポインタを介して格納されます。そのポインタは int へのポインタでなければなりません。 * フラグで抑制することができますが、これは変換ではありません。

小数点文字はプログラムのロケール (カテゴリ LC_NUMERIC) で定義されます。

後方互換性のために、‘ %\0’の“変換”はただちに EOF を返します。

戻り値

これらの関数は、割り当てられた入力項目数を返します。この数は提供されたものよりも少なくでき、または、一致が成功しなかった場合、 0 なることさえあります。 0 は、利用可能な入力があった間、変換が割り当てられなかったことを示します。一般的に、これは‘ %d’変換のためのアルファベット文字のような、無効の入力文字のためです。ファイルの終りが生じるようになんらかの変換の前に入力の失敗が生じたなら、値 EOF が返されます。変換が始まった後、エラーまたはファイルの終りが生じる場合、成功して終了した変換の数が返されます。

関連項目

fgetwc(3), scanf(3), wcrtomb(3), wcstod(3), wcstol(3), wcstoul(3), wprintf(3)

規格

fwscanf(), wscanf(), swscanf(), vfwscanf(), vwscanf() と vswscanf() 関数は、 ISO/IEC 9899:1999 (“ISO C99”) に適合しています。

バグ

scanf(3) に文書化されたバグに加えて、 wscanf() は、文字クラス変換 (‘ %[’) で文字の範囲を指定するための“ A-Z”記法をサポートしません。