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