マニュアルページ istream.3
名前
istream - 書式つき / 書式なし入力
形式
#include <iostream.h>
typedef long streampos;
typedef long streamoff;
class unsafe_ios {
public:
// 公開された型
// ストリーム操作モード
enum open_mode {
in = 0x01, // 読み取り用にオープン
out = 0x02, // 書き込み用にオープン
ate = 0x04, // EOF までシークする
app = 0x08, // 追加モード: EOF 以降に追加
trunc = 0x10, // ファイルがあれば内容をクリア
nocreate = 0x20, // ファイルがなければオープンを失敗させる
noreplace= 0x40 // ファイルがあればオープンを失敗させる
};
// ストリームのシーク方向
enum seek_dir { beg=0, cur=1, end=2 };
// 書式化フラグ
enum {
skipws = 0x0001, // 入力の空白を読み飛ばす
left = 0x0002, // 左揃えで出力する
right = 0x0004, // 右揃えで出力する
internal = 0x0008, // 正負号や基数指示子の後のパディング
dec = 0x0010, // 10 進数の変換
oct = 0x0020, // 8 進数の変換
hex = 0x0040, // 16 進数の変換
showbase = 0x0080, // 基数指示子を出力
showpoint = 0x0100, // 小数点を強制的に使用
// (浮動小数点型での出力時)
uppercase = 0x0200, // 16 進数を大文字で出力
showpos = 0x0400, // 正の整数に "+" 記号を追加
scientific= 0x0800, // 1.2345E2 浮動小数点表記を使用
fixed = 0x1000, // 123.45 浮動小数点表記を使用
unitbuf = 0x2000, // 挿入後すべてのストリームをフラッシュ
stdio = 0x4000 // 挿入後、標準出力や標準エラーを
// フラッシュ
};
// 残りの部分については ios(3CC4) を参照 ...
};
class unsafe_istream : virtual public unsafe_ios {
public:
// 公開された関数
// 書式化されていない入力関数
unsafe_istream& read(char* ptr, int count);
unsafe_istream& read(unsigned char* ptr, int count);
unsafe_istream& get(char* ptr, int count, char delim='\n');
unsafe_istream& get(streambuf& sbuf, char delim='\n');
unsafe_istream& get(char& ch);
unsafe_istream& get(unsigned char& ch);
unsafe_istream& get_line(char* ptr, int count, char delim='\n');
unsafe_istream& get_line(unsigned char* ptr, int count, char delim='\n');
int get();
int peek();
unsafe_istream& ignore(int count=1, int delim=EOF);
unsafe_istream& putback(char ch);
// ワイド文字
unsafe_istream& get(wchar_t* wptr, int count , wchar_t wdelim=L'\n');
unsafe_istream& get(wchar_t& wc);
unsafe_istream& getline(wchar_t* wptr, int count, wchar_t wdelim=L'\n');
unsafe_istream& wignore(count=1, wdelim=WEOF);
// その他の関数
int ipfx(int noform=0);
int wipfx(int noform=0); // ワイド文字 ipfx
unsafe_istream& seekg(streampos pos);
unsafe_istream& seekg(streamoff offset, unsafe_ios::seek_dir dir);
streampos tellg();
int sync();
int gcount();
public:
// 公開された演算子関数
unsafe_istream& operator>> (char* buf);
unsafe_istream& operator>> (unsigned char* buf);
unsafe_istream& operator>> (char&);
unsafe_istream& operator>> (unsigned char&);
unsafe_istream& operator>> (short&);
unsafe_istream& operator>> (int&);
unsafe_istream& operator>> (long&);
unsafe_istream& operator>> (unsigned short&);
unsafe_istream& operator>> (unsigned int&);
unsafe_istream& operator>> (unsigned long&);
unsafe_istream& operator>> (float&);
unsafe_istream& operator>> (double&);
unsafe_istream& operator>> (streambuf* sbufp);
unsafe_istream& operator>> (unsafe_istream& (*manip)(unsafe_istream&));
unsafe_istream& operator>> (unsafe_ios& (*manip)(unsafe_ios&) );
public:
// ワイド文字
unsafe_istream& operator>>(wchar_t&);
unsafe_istream& operator>>(wchar_t*);
public:
// 公開されたコンストラクタ
unsafe_istream(streambuf* sbuf);
};
class istream : virtual public ios, public unsafe_istream {
public:
//公開された関数
// 書式化されていない入力関数
istream& read(char* ptr, int count);
istream& read(unsigned char* ptr, int count);
istream& get(char* ptr, int count, char delim='\n');
istream& get(unsigned char* ptr,int count, char delim='\n');
istream& get(unsigned char& ch);
istream& get(char& ch);
istream& get(streambuf& sb, char delim ='\n');
istream& getline(char* ptr, int count, char delim='\n');
istream& getline(unsigned char* ptr, int count, char delim='\n')
int get();
int peek();
istream& ignore(int len=1,int delim=EOF);
istream& putback(char ch);
// ワイド文字
istream& get(wchar_t* wptr, int count, wchar_t wdelim=L'\n');
istream& get(wchar_t& wc);
istream& getline(wchar_t* wptr, int count, wchar_t wdelim=L'\n');
istream& wignore(int count=1, wchar_t wdelim=WEOF);
wint_t peekw();
// その他の関数
int ipfx(int noform=0);
istream& seekg(streampos pos);
istream& seekg(streamoff offset, seek_dir dir);
streampos tellg();
int sync();
int gcount();
public:
// 公開された演算子関数
istream& operator>>(char*);
istream& operator>>(unsigned char*);
istream& operator>>(char&);
istream& operator>>(unsigned char&);
istream& operator>>(short&);
istream& operator>>(int&);
istream& operator>>(long&);
istream& operator>>(unsigned short&);
istream& operator>>(unsigned int&);
istream& operator>>(unsigned long&);
istream& operator>>(float&);
istream& operator>>(double&);
istream& operator>>(streambuf*);
istream& operator>>(istream& (*)(istream&));
istream& operator>>(ios& (*)(ios&));
public:
// ワイド文字
istream& operator>>(wchar_t&);
istream& operator>>(wchar_t*);
public:
// 公開されたコンストラクタ
istream(streambuf*);
};
class istream_withassign : public istream {
public:
istream_withassign();
istream_withassign& operator= (istream&);
istream_withassign& operator= (streambuf*);
};
extern istream_withassign cin;
ios& dec(ios&);
ios& hex(ios&);
ios& oct(ios&);
istream& ws(istream&);
unsafe_ios& dec(unsafe_ios&) ;
unsafe_ios& hex(unsafe_ios&) ;
unsafe_ios& oct(unsafe_ios&) ;
unsafe_istream& ws(unsafe_istream&) ;
機能説明
クラス istream は、対応する streambuf からの書式つきおよび書
式なしのデータの抽出 (入力) をサポートします。
istream オブジェクトとそのメンバー関数は、mutex ロックにより
複 数 の ス レッ ド の 同 時 ア ク セ ス か ら保護されます。
unsafe_istream オブジェクトとそのメンバー関数は mutex ロック
を実装しません。この違いを除き、 istream と unsafe_istream、
およびそれぞれの関数の機能は同じです。マルチスレッド環境にお
け る安全性と mutex ロックの詳細と入出力ストリームとの関係に
ついては、 MT-Safe libC Programmers Guide を参照してく だ さ
い。
コンストラクタと代入
istream(sbufp)
sbufp が指すポインタをストリームに対応づけ、 ios 状態を
初期化します。
istream_withassign()
初期化を行いません。
istream_withassign isw = sbufp
sbufp が指す streambuf を isw に対応づけ、 isw を完全に
初期化します。
istream_withassign isw = istr
istr に対応する streambuf を isw に対応づけ、 isw を 完
全に初期化します。
ワイド文字操作について
ワイド文字を生成する入力関数は、不正なバイトの列を検出すると
failbit を セットします。バイトのシーケンスを不正と見なすの
は、それが現在のロケールでの複数バイト・エンコーディングと解
釈できない場合です。
「先読み」を行うような複数バイトの入力操作の直後に単一バイト
の入力操作を行わないでください。単一バイト入力操作は、シーク
( seekg 後に行うことができます。 streambufs でサポートが必要
な のは 1 バイトの先読みだけであるため、先読みを行う複数バイ
ト入力操作は、入力ストリーム自身に「先読みした」バイトをバッ
ファリングすることがあります。 seekg と tellg では、そのよう
な内部バッファリングが考慮されています。
入力接頭辞関数
int i = istr.ipfx(noform)
すべての抽出操作に共通の準備を行います。書式つきの抽 出
で は ipfx(0) を呼び出し、書式なしの抽出では ipfx(1) を
呼び出します。 istr のエラー状態がゼロでないとき、 ipfx
は 直 ち に ゼ ロを返します。ストリームが istr に結合 (
ios(3CC4) の tie を参照) され、かつ noform がゼロ の と
き、 結合されているストリームはフラッシュされます。スト
リームの skipws フラグがセットされ、かつ noform がゼ ロ
のとき、先頭の空白類文字 ( iswhite で定義、 ctype(3C++)
を参照) が読み飛ばされます。関数 ipfx の戻り値は、何 ら
か のエラーが検出された場合はゼロ、エラーがなかった場合
はゼロ以外です。
int i = istr.wipfx(noform)
ワイド文字抽出関数は、 ipfx の代わりに wipfx を使用しま
す。 wipfx と ipfx() は似ていますが、 ipfx が単一バイト
の空白文字を読み飛ばすのに対し、 wipfx() は iswspace で
定 義されたすべての複数バイトの空白を読み飛ばします。さ
らに、 wipfx() は不正なバイトの列があると ios::failbit
をセットします。この関数は、ANSI で提案された iostreams
インタフェースにないため、アプリケーションコードから 直
接呼び出すことは避けてください。
書式つき入力 (抽出) 関数
これらの関数は ipfx(0) を呼び出します。 ipfx(0) の戻り値がゼ
ロ の場合は、それ以上の処理を行いません。 ipfx(0) の戻り値が
ゼロ以外の場合、 ios::skipws がセットされていれば先頭の空 白
類 文字を読み飛ばします。 istream の中に空白類しか残っていな
い場合、それらのすべてを処分し、 ios::failbit をセット し ま
す。ワイド文字対応の書式つき入力関数は wipfx(0) を呼び出し、
それがゼロを返すと何もしないで返します。
istr >> sbufp
istr から文字を抽出し、抽出した文字 を sbufp が 指 す
streambuf に 挿 入します。戻り値は常に istr への参照で
す。この関数を使用すればストリームを効率よくコピーで き
ま すが、その場合にコピー先とコピー元のストリームがとも
に結合されていないことを確かめる必要があります。
使用例 :
#include <iostream.h>
main()
{ // cin を cout にコピー
cin.tie(0);
cout.tie(0);
cin >> cout.rdbuf(); // rdbuf については ios(3CC4) を参照
return 0;
}
istr >> x
istr から文字を抽出し、 x の型に従って抽出した文字を 変
換 します。 ipfx の戻り値がゼロのとき、文字の抽出は行わ
ず、 x を変更しません。検出したエラーはすべて istr のエ
ラー 状態に記録されます。一般に、 ios::failbit は、次に
入力する文字が型に適していなかったということを意味し ま
す。 たとえば、数値型に対して先頭に文字が入力されたり、
任意の型に対して先頭に空白類が入力される場合などで す。
型 に 適 し て い な い 文 字は抽出されません。一般に、
ios::badbit は抽出できる文字がなかったことを意 味 し ま
す。 たとえば、ファイルの終端に達した場合などです。これ
らの関数の戻り値は常に istr への参照です。独自に関数 を
作成する場合、その書式は次のようにしてください。
istream& operator>> (istream&, SomeType)
また、上記の原則に従ってください。
x の型と istream の書式状態 ( ios(3CC4) 参照) によ り、
抽 出 と 変換の具体的な内容が決まります。これらの関数は
istream の状態を変更しませんが、変数 width は書式つきの
抽 出が行われるたびにゼロに再設定されます。定義済みの書
式つき抽出関数は次のとおりです。
char&, unsigned char&
1 文字抽出し、それを x に格納します。
wchar_t&
wipfx(0) が正常終了し、かつファイルの終端を検出していな
け れば、1 つの複数バイト文字を抽出し、抽出した文字をワ
イド文字として x に格納します。不正なバイトの列を検出し
た場合は ios::failbit をセットします。
short&, unsigned short&
int&, unsigned int&
long&, unsigned long&
文字を抽出し、 istream の書式フラグの変換基数に従って、
抽出した文字を整数値に変換します。変換後の文字は、 x の
値に格納します。先頭の文字がプラス符号 (`+') またはマイ
ナス符号 (`-') の場合があります。その後、 ios::basfield
フラグが dec、oct、hex の場合、抽出された文字はそれぞれ
10 進数、8 進数、16 進数として扱われます。これらのフラ
グがどれもセットされていない場合、数字は C++ の整定数と
同様に解釈されます。すなわち、先頭の 2 文字が ``0x'' ま
たは ``0X'' のときは 16 進数、それ以外の場合で先頭の 文
字 が `0' の場合は 8 進数、それ以外の場合は 10 進数にな
ります。抽出 (と変換) は最初に見つけた数字以外の文字 で
停止します (この数字以外の文字は抽出されません)。有効な
数字は 8 進数の場合は `0' から `7'、10 進数の場合は `0'
から `9'、16 進数の場合は `0' から `9' と、`a' から `f'
または `A' から `F' です。有効な数字が 1 つもなかった場
合、 エラーフラグ ios::failbit がセットされます。a 〜 f
や A 〜 F は数字でなくてもかまいません。エラーが発生 す
ると、 x の値は変更されません。
float&, double&
文字を抽出し、浮動小数点定数についての C++ の規則に従っ
て、 抽出した文字を浮動小数点数値に変換します。変換した
値は x の値に格納します。抽出された文字が正しい形式の浮
動小数点数で始まっていないと、エラーフラグ ios::failbit
がセットされます。この場合でも、エラーが検出された場 所
に よっ て は、一部の文字が抽出される場合があります。エ
ラーが発生すると、 x の値は変更されません。
char*, unsigned char*
空白類文字を検出するまで抽出を行い、抽出した文字を x が
指 す 配 列に格納します。空白類は抽出しません (ただし、
ipfx は先頭の空白類文字を破棄することがあります)。書 式
化変数 width ( ios(3CC4) を参照) の値がゼロ以外のとき、
最大で width-1 個の文字が抽出されます。文字が抽出されな
かっ た場合でも、 x には終端の NULL(0) が常に格納されま
す。抽出できる文字が何もなかった場合、 エ ラー フ ラ グ
ios::failbit がセットされます。
wchar_t*
char* の抽出関数と同様の機能を持ちます。異なるのは、 複
数 バイト空白類文字を検出するまで、複数バイトで表された
文字をワイド文字の配列にデコードするという点です。さ ら
に、 不 正 なバイトの列を検出した場合は ios::failbit を
セットします。
書式なし入力 (抽出) 関数
これらの関数は ipfx(1) を呼び出します。 ipfx(1) の戻り値がゼ
ロのときはそれ以上の処理を行いません。先頭の空白類の読み飛ば
しは行わず、さらに変換も行いません。ワイド文字対応の入力関数
は、 ipfx(1) の代わりに wipfx(1) を呼び出します。
int c = istr.get()
istr から次の文字を抽出し、抽出した文字を返します。抽出
可 能 な 文 字 が 残っ て いない場合は EOF を返します。
ios::failbit はセットしません。
istr.get(ch)
istr から次の文字を抽出し、抽出した文字を ch に格納しま
す。抽出可能な文字が残っていない場合は、 EOF を格納しま
す。 EOF の検出後 に 抽 出 が 試 み ら れ た 場 合 は、
ios::failbit をセットします。戻り値は常に istr への参照
です。
istr.get(ptr, count, delim)
istr から文字を抽出し、抽出した文字を ptr から 始 ま る
char 型 配 列に格納します。 count-1 個の文字を抽出する
か、 delim に一致する文字を検出するか、そのどちらか早い
時点で抽出は停止します。 delim で指定された文字を検出し
ても、その文字の抽出や格納は行いません。この関数は、 文
字 の抽出を全く行わなかった場合でも、常に終端の NULL(0)
を格納します。文字を格納する前に EOF を検出した場合にか
ぎ り、 ios::failbit をセットします。戻り値は常に istr
への参照です。
istr.get(sbuf, delim)
istr から文字を抽出し、抽出した文字を streambuf sbuf に
格納します。 delim (または EOF ) に一致する文字を検出す
るか、 sbuf への格納に失敗するか、そのどちらか早い時 点
で 抽 出は停止します。 delim で指定された文字を検出して
も、その文字の抽出や格納は行いません。 delim が EOF の
と き、抽出が停止するのは、入力データが終了するか、格納
に失敗した場合だけです。この関数は、 sbuf への格納が 失
敗 した場合にかぎり ios::failbit をセットします。戻り値
は常に istr への参照です。
istr.get(wc)
istr から次の文字を抽出し、抽出した文字をそのワイド文字
表 現で wc に格納します。抽出可能な文字が残っていない場
合は WEOF を格納します。また、ファイルの終端の検出後 に
抽 出が試みられた場合、または不正なバイトの列を検出した
場合は ios::failbit をセットします。戻り値は istr へ の
参照です。
istr.get(wptr, count, wdelim)
単一バイト文字を処理するときと同じ で す が、 wptr が
wchar_t 型の配列を指し、 wdelim が wchar_t 型であるとい
う点が異なります。不正なバイトの列を検出 し た 場 合 は
ios::failbit を セットします。戻り値は istr への参照で
す。
istr.getline(ptr, count, delim)
この関数は、 istr.get(ptr, count, delim) と同じ操作を行
います。ただし、 delim を検出した場合、その文字を抽出し
ます (格納は行いません)。 count-1 個の文字を抽 出 す る
と、その次の文字は delim に一致していても istr に残され
ます。この関数の戻り値は常に istr への参照です。
istr.getline(wptr, count, wdelim)
単一バイト文字を処理するときと同じ で す が、 wptr が
wchar_t 型の配列を指し、 wdelim が wchar_t 型であるとい
う点が異なります。不正なバイトの列を検出 し た 場 合 は
ios::failbit をセットします。戻り値は、 istr への参照で
す。
istr.ignore(count, delim)
istr から文字を抽出して破棄します。 delim に一致する 文
字 を検出するか、 count 個の文字を検出するか、 EOF を検
出するか、その最も早い時点で抽出は停止します。 こ の と
き、文字 delim を抽出します。 delim が EOF のとき、入力
データのすべてを破棄します。この関数の戻り値は常に istr
への参照です。
istr.wignore(count=1, wdelim=WEOF)
ignore() と同じですが、 wdelim が WEOF で な い と き、
count は読み飛ばすバイト数ではなく、読み飛ばす複数バイ
ト文字の数を示します。 wdelim が WEOF の場合でも、不 正
な バイトの列を検出すれば ios::failbit をセットして停止
します。戻り値は istr への参照です。
istr.read(ptr, count)
istr から文字を抽出し、抽出した文字を ptr から 始 ま る
char 型配列に格納します。 count 個の文字を抽出するか、
EOF を検出するか、そのどちらか早い時点で抽出は停止し ま
す。 count 個 の文字を抽出する前に EOF を検出すると、
ios::failbit をセットします。戻り値は常に istr への参照
で す。 こ の 関 数 に よ り 抽 出 さ れ た文字の数は、
istr.gcount() (下記参照) を呼び出して調べることができま
す。
位置決め関数
これらの関数は、 istream に対応する streambuf の入力ポインタ
を操作します。詳細については、 sbuf.pub(3CC4) を参照してくだ
さい。複数バイト入力操作を行なった場合、 tellg() で取得し た
値 が streambuf の入力ポインタと異なる場合があります。しか
し、その場合でも、 istream 上ではすべての操作とシークが正 し
く同期します。
istr.seekg(pos)
入力ポインタの位置を設定し、 istr を返します。
istr.seekg(offset, dir)
入力ポインタの位置を設定し、 istr を返します。
streampos pos = istr.tellg()
入力ポインタの現在の位置を返します。複数バイト入力操 作
を 行なった場合、 tellg() で取得した値が streambuf の入
力ポインタと異なる場合があります。しかし、その 場 合 で
も、 istream 上ではすべての操作とシークが正しく同期しま
す。
その他の関数
int i = istr.gcount()
最後に呼び出された書式なし入力関数によって istr から 抽
出 された文字の数を返します。書式つき入力関数が書式なし
関数を呼び出し、結果として文字数が変化する場合がある の
で 注 意 してください。書式なしワイド文字入力関数の後で
は、 gcount() は抽出した (複数バイト) 文字の数を返し ま
す。
int i = istr.peek()
まず istr.ipfx(1) を呼び出します。 ipfx の戻り値がゼ ロ
で あるか、 istr の現在の位置が EOF のときは、 EOF を返
します。それ以外の場合は次の文字を返します (抽出はし ま
せん)。
int i = istr.peekw()
wipfx(1) を呼び出し、それ が 異 常 終 了 し た 場 合 は
(wint_t)WEOF を返します。不正なバイトの列を検出した場合
は ios::failbit をセットし、 WEOF を返します。正常終 了
時 には stream の次の文字をワイド文字として返します。こ
のとき、入力ポインタは移動しません。
istr.putback(ch)
istr.fail() の戻り値がゼロ以外のとき、この関数は何も し
ないで返します。 istr.fail() の戻り値がゼロの場合、文字
ch をプッシュバックすることで、 istr に対応する stream-
buf のバックアップを試みます。抽出を行わないため、 ipfx
は呼び出しません。異常終了したとき は ios::failbit を
セッ トします。一般に、 c は streambuf の入力ポインタの
次にある文字 (通常は最後に抽出された文字) に一致しな け
れ ば な りません。読み取り専用のメモリー内バッファから
データが入力されている場合があります。
int i = istr.sync()
内部データ構造と文字の外部ソースとを実装で定義された 方
法で強制的に対応づけます。仮想関数 istr.rdbuf()->sync()
を呼び出します。もちろん、この仮想関数の動作はバッ ファ
クラスの実際の型に依存します。エラー時の戻り値は EOF で
す。
定義済みマニピュレータ
マニピュレータは、外見上、挿入または抽出されたオブジェクトと
して使用されることがありますが、実際はストリームの状態を変更
するだけです。詳細については、 manip(3CC4) と ios(3C++) を参
照してください。入力ストリーム用に、以下のマニピュレータが定
義されています。
istr >> manip
manip(istr) の呼び出しと等価です。
istr >> dec
istr の変換基数を 10 に設定します。
istr >> oct
istr の変換基数を 8 に設定します。
istr >> hex
istr の変換基数を 16 に設定します。
istr >> ws
istr から連続した空白類文字を抽出し、破棄します。
関連項目
ios.intro(3CC4)、 ctype(3C)、 ios(3CC4)、 manip(3CC4)、
sbufpub(3CC4)、 stdiobuf(3CC4)、
『C++ ライブラリ・リファレンス』の第 3 章「iostream ライブラ
リ」および第 4 章「マルチスレッド環境での従来型の iostream
ライブラリの使用」