マニュアルページ 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
     ライブラリの使用」