マニュアルページ ssbuf.3




名前

     ssbuf - 文字配列用バッファクラス


形式

     #include <strstream.h> // <iostream.h> を取り込む
     class strstreambuf : public streambuf {
     public:
               strstreambuf();
               strstreambuf(int n);
               strstreambuf(void* (*a)(long), void (*f)(void*));
               strstreambuf(char* _s, int, char* _strt=0);
               ~strstreambuf();

          void    freeze_unlocked(int = 1);
          void    freeze(int = 1);
          char*   str_unlocked();
          char*   str();
     virtual int     doallocate();
     virtual int     overflow(int);
     virtual int     underflow();
     virtual streambuf* setbuf(char*, int);
     virtual streampos seekoff(streamoff, unsafe_ios::seek_dir, int);
     };


機能説明

     クラス strstreambufは、文字の入力元または出力先とし て  char
     配 列 (文字列) を使用するように特殊化された streambuf です。
     文字は配列からフェッチ (入力) され、配列によって消費 (配列に
     出 力 )  さ れ ま す。  streambuf  の 基 本 操 作 については
     sbufprot(3C++) と sbufpub(3C++) で説明します。入力ポインタと
     出力ポインタは接続 (アタッチ) された配列を指し、入力ポインタ
     または出力ポインタの移動は、 char* のインクリメントまたは デ
     クリメントに対応します。

     streambuf を「MT-安全」、すなわちマルチスレッド環境で正し く
     機能するようにするため、公開メンバー関数のそれぞれにロックが
     使用されています。パフォーマンスが重要になるシングルスレッド
     の ア プリケーションのために、各関数にロックを使用しないバー
     ジョンが導入されました。ロックを使用しない関数は、オリジナル
     の 関 数 名に _unlocked という接尾辞が付いています。マルチス
     レッド環境に対して安全でない (MT-unsafe) ことを除き、ロッ ク
     を使用しない関数はそれぞれのオリジナルの関数と同じ機能を持ち
     ます。詳細については、『C++ ライブラリ・リファレンス』 の  4
     章「マルチスレッド環境における iostream ライブラリの使用」を
     参照してください。

     strstreambuf は、動的モードまたは静的モードのいずれかで使 用
     できます。動的モードでは、配列が自動的に割り当てられ、与えら
     れた文字列を格納できるように必要に応じて拡張されます。さらに
     空間が必要になった場合は、新しいバッファ領域が割り当てられ、
     古い配列から新しい領域にデータがコピーされた後、古い配列は削
     除されます。静的モードでは、ユーザーが提供した固定長の配列が
     使用されます。この配列は、新しいバッファに移動したり変更する
     ことはできません。また、自動的に削除されることもありません。
     動的モードの strstreambuf の拡張は禁止することができます。こ
     の 操作を「フリーズ」と呼びます。フリーズされた strstreambuf
     、または静的な strstreambuf は、 char* に変換して C 形式の文
     字 列 を 必 要 と する式で使用できます。フリーズされた動的な
     strstreambuf はフリーズを解除して、もう一度拡張可能にする こ
     とができます。

  コンストラクタ
     strstreambuf()
          空の、動的な、フリーズされていない strstreambuf を作 成
          し ます。文字列のための領域は、必要に応じて自動的に割り
          当てられます。挿入される文字数の最小値が分かっている 場
          合 は、小さな配列の割り当てや解放が繰り返されることを避
          けるために、コンストラクタ strstream(int) でバッファ を
          作成するか、 setbuf() (後述) を使用してください。

     strstreambuf(n)
          空の、動的な、フリーズされていない strstreambuf を作 成
          します。初期のバッファサイズとして少なくとも n バイトを
          確保します。

     strstreambuf(alloc, del)
          空の、動的な、フリーズされていない strstreambuf を作 成
          し ます。文字列のための領域は、必要に応じて自動的に割り
          当てられます。 new および delete は使用されず、提供され
          ている関数 alloc と del が呼び出されます。 alloc 関数は
          割り当てるバイト数を指定する long 型のパラメタを取ら な
          け ればなりません。この関数の戻り値は、正常終了時には割
          り当てられた領域へのポインタ ( void* 型)、異常終了時 に
          は ゼ ロ です。 alloc が NULL のときは new が使用されま
          す。 del 関数は alloc によって取得した void* 型のポイン
          タ 値を引数に取らなければなりません。この関数の戻り値の
          型は void です。 del が NULL のときは delete が使用され
          ま す。このコンストラクタの使用時には、 alloc と del と
          の間の互換性に注意する必要があります。

     strstreambuf(ptr, len, putp)
          ptr が指すバッファを使用する静的な strstreambuf を作 成
          します。 len が正の場合で、 putp が NULL の場合は、 ptr
          で始まる len バイトが使用されます。 putp が NULL でない
          場 合は、 len は無視され、 ptr から putp までが初期入力
          領域として使用されます。 len がゼロの場合、 ptr は NULL
          で終わる文字列を指していると見なされ、NULL バイトまでの
          領域 (NULL バイトは含まない) がバッファとして使用されま
          す。 len が負の場合、バッファの長さは無制限と見なされて
          しまいます。入力ポインタは ptr に初期設定されます。出力
          ポ インタは putp に初期設定されます。 putp が NULL の場
          合、格納操作はエラーと見なされます。

          使用例 :
          strstreambuf greeting("Hello, world!", 0, 0);
               指定されたテキストで構成されるバッファを作成 し ま
               す。 デー タを上書きしたり、拡張することはできませ
               ん。
          char *hi = "Hello, world!";
          strstreambuf greeting(hi, 0, hi+7);
               指定されたテキストで構成されるバッファを作成 し ま
               す。 `w' から `!' までのデータは上書きできますが、
               拡張することはできません。
          char *hi = "Hello, world!";
          strstreambuf greeting(hi, 5, hi);
               指定されたテキストで構成されるバッファを作成 し ま
               す。 データの "Hello" の部分は読み取ったり上書きす
               ることができます。バッファの残りの部分にはアクセス
               できません。

  メンバー関数
     ssbuf.freeze(i)
          i がゼロでない場合は、動的なバッファをフリーズしま す。
          ゼ ロの場合は、バッファのフリーズを解除します。バッファ
          をフリーズすると、 strstreambuf が破棄されて も、 そ の
          バッ ファ が 自動的に削除されることはありません。また、
          バッファが現在のサイズより拡張されることはありませ ん。
          バッ ファへのポインタの取得を許可する場合には、そのバッ
          ファをフリーズしてから明示的にフリーズを解除されるま で
          信 頼性を確保することが必要です。動的なバッファはフリー
          ズを解除することで自動的に拡張または削除されるように な
          り ます。静的なバッファは自動的に拡張されたり削除される
          ことがないため、フリーズ操作をしてもバッファは NULL  で
          終わる文字列としてみなされず終了しません。

     char* p = ssbuf.str()
          ssbuf をフリーズし、バッファの先頭を指すポインタを返 し
          ます。 ssbuf が動的モードでバッファが空の場合は NULL ポ
          インタを返す場合があります。

     streambuf* sbp = ssbuf.setbuf(ptr, len)
          ptr が NULL でないとき、要求は無視されます。静的また は
          動 的な strstreambuf のバッファを置き換えることはできま
          せん。 ptr が NULL の場合、 len の値が保存され、次回 の
          動的モードの割り当てで少なくとも len バイトが確保されま
          す (このことは次回の割り当てだけに適用され、その後  len
          の値は破棄されます)。バッファが拡張されようとしていると
          き、この関数を使用して適切なサイズの割り当てを強制す れ
          ば、 小さな領域の割り当てと解放が頻繁に行われることを避
          けることができます。


関連項目

     ios.intro(3C++), ios(3C++), sbufprot(3C++), sbufpub(3C++)
     strstream(3C++),

     『C++ ライブラリ・リファレンス』
          3 章「iostream ライブラリ」

          4 章「マルチスレッド環境における iostream ライブラリの
          使用」