basic_filebuf クラス

文字の特徴がクラス Tr によって決まる型 Char_T の要素と、外部ファイルに格納されている要素のシーケンスとの間でやり取りされる転送を制御するストリーム バッファーを記述します。

構文

template <class Char_T, class Tr = char_traits<Char_T>>
class basic_filebuf : public basic_streambuf<Char_T, Tr>

パラメーター

Char_T
ファイル バッファーの基本要素。

Tr
ファイル バッファーの基本要素の特徴 (通常は char_traits<Char_T>)。

解説

このクラス テンプレートは、文字の特徴がクラス Tr によって決まる型 Char_T の要素と、外部ファイルに格納されている要素のシーケンスとの間でやり取りされる転送を制御するストリーム バッファーを記述します。

basic_filebuf<Char_T, Tr> クラスのオブジェクトは、開いているファイルに関連付けられているストリームを制御する FILE オブジェクトを示すファイル ポインターを格納します。 さらに、プロテクト メンバー関数である overflow と underflow で使用される 2 つのファイル変換ファセットへのポインターも格納します。 詳細については、basic_filebuf::openを参照してください。

例

次の例では、pubsetbuf() メソッドを呼び出して、basic_filebuf<wchar_t> 型のオブジェクトの内部バッファーに Unicode 文字を強制的に格納しています。

// unicode_basic_filebuf.cpp
// compile with: /EHsc

#include <iostream>
#include <string>
#include <fstream>
#include <iomanip>
#include <memory.h>
#include <string.h>

#define IBUFSIZE 16

using namespace std;

void hexdump(const string& filename);

int main()
{
    wchar_t* wszHello = L"Hello World";
    wchar_t wBuffer[128];

    basic_filebuf<wchar_t> wOutFile;

    // Open a file, wcHello.txt, then write to it, then dump the
    // file's contents in hex
    wOutFile.open("wcHello.txt",
        ios_base::out | ios_base::trunc | ios_base::binary);
    if(!wOutFile.is_open())
    {
        cout << "Error Opening wcHello.txt\n";
        return -1;
    }
    wOutFile.sputn(wszHello, (streamsize)wcslen(wszHello));
    wOutFile.close();
    cout << "Hex Dump of wcHello.txt - note that output is ANSI chars:\n";
    hexdump(string("wcHello.txt"));

    // Open a file, wwHello.txt, then set the internal buffer of
    // the basic_filebuf object to be of type wchar_t, then write
    // to the file and dump the file's contents in hex
    wOutFile.open("wwHello.txt",
        ios_base::out | ios_base::trunc | ios_base::binary);
    if(!wOutFile.is_open())
    {
        cout << "Error Opening wwHello.txt\n";
        return -1;
    }
    wOutFile.pubsetbuf(wBuffer, (streamsize)128);
    wOutFile.sputn(wszHello, (streamsize)wcslen(wszHello));
    wOutFile.close();
    cout << "\nHex Dump of wwHello.txt - note that output is wchar_t chars:\n";
    hexdump(string("wwHello.txt"));

    return 0;
}

// dump contents of filename to stdout in hex
void hexdump(const string& filename)
{
    fstream ifile(filename.c_str(),
        ios_base::in | ios_base::binary);
    char *ibuff = new char[IBUFSIZE];
    char *obuff = new char[(IBUFSIZE*2)+1];
    int i;

    if(!ifile.is_open())
    {
        cout << "Cannot Open " << filename.c_str()
             << " for reading\n";
        return;
    }
    if(!ibuff || !obuff)
    {
        cout << "Cannot Allocate buffers\n";
        ifile.close();
        return;
    }

    while(!ifile.eof())
    {
        memset(obuff,0,(IBUFSIZE*2)+1);
        memset(ibuff,0,IBUFSIZE);
        ifile.read(ibuff,IBUFSIZE);

        // corner case where file is exactly a multiple of
        // 16 bytes in length
        if(ibuff[0] == 0 && ifile.eof())
            break;

        for(i = 0; i < IBUFSIZE; i++)
        {
            if(ibuff[i] >= ' ')
                obuff[i] = ibuff[i];
            else
                obuff[i] = '.';

            cout << setfill('0') << setw(2) << hex
                 << (int)ibuff[i] << ' ';
        }
        cout << "  " << obuff << endl;
    }
    ifile.close();
}

Hex Dump of wcHello.txt - note that output is ANSI chars:
48 65 6c 6c 6f 20 57 6f 72 6c 64 00 00 00 00 00   Hello World.....

Hex Dump of wwHello.txt - note that output is wchar_t chars:
48 00 65 00 6c 00 6c 00 6f 00 20 00 57 00 6f 00   H.e.l.l.o. .W.o.
72 00 6c 00 64 00 00 00 00 00 00 00 00 00 00 00   r.l.d...........

コンストラクター

コンストラクター	説明
basic_filebuf	basic_filebuf 型のオブジェクトを構築します。

Typedefs

型名	説明
char_type	型名を Char_T テンプレート パラメーターに関連付けます。
int_type	basic_filebuf のスコープ内のこの型を、Tr スコープ内の同じ名前の型と同等にします。
off_type	basic_filebuf のスコープ内のこの型を、Tr スコープ内の同じ名前の型と同等にします。
pos_type	basic_filebuf のスコープ内のこの型を、Tr スコープ内の同じ名前の型と同等にします。
traits_type	型名を Tr テンプレート パラメーターに関連付けます。

メンバー関数

メンバー関数	説明
閉じる	ファイルを閉じます。
is_open	ファイルが開いているかどうかを示します。
open	ファイルを開きます。
overflow	いっぱいのバッファーに新しい文字が挿入されたときに呼び出すことができる、プロテクト仮想関数。
pbackfail	プロテクト仮想メンバー関数が要素を入力ストリームに戻そうと試み、その要素を現在の要素に (次のポインターによって指されるように) します。
seekoff	プロテクト仮想メンバー関数が、制御されているストリームの現在の位置を変更しようと試みます。
seekpos	プロテクト仮想メンバー関数が、制御されているストリームの現在の位置を変更しようと試みます。
setbuf	プロテクト仮想メンバー関数が、各派生ストリーム バッファーに固有の操作を実行します。
Swap	この basic_filebuf の内容を、指定された basic_filebuf パラメーターの内容と交換します。
sync	プロテクト仮想関数が、制御されているストリームと、関連付けられている外部ストリームとを同期しようと試みます。
uflow	入力ストリームから現在の要素を抽出するプロテクト仮想関数。
underflow	入力ストリームから現在の要素を抽出するプロテクト仮想関数。

要件

ヘッダー:<fstream>

名前空間: std

basic_filebuf::basic_filebuf

basic_filebuf 型のオブジェクトを構築します。

basic_filebuf();

basic_filebuf(basic_filebuf&& right);

解説

最初のコンストラクターは、入力バッファーと出力バッファーを制御するすべてのポインターに Null ポインターを格納します。 また、ファイル ポインターにも Null ポインターを格納します。

2 番目のコンストラクターは、右辺値参照として扱われる right のコンテンツでオブジェクトを初期化します。

basic_filebuf::char_type

型名を Char_T テンプレート パラメーターに関連付けます。

typedef Char_T char_type;

basic_filebuf::close

ファイルを閉じます。

basic_filebuf<Char_T, Tr> *close();

戻り値

メンバー関数は、ファイル ポインターが Null ポインターの場合に、Null ポインターを返します。

解説

close は fclose(fp) を呼び出します。 その関数がゼロ以外の値を返す場合、関数は Null ポインターを返します。 それ以外の場合は、this を返してファイルが正常に閉じられたことを示します。

ワイド ストリームの場合、ストリームが開いてから、または streampos への最後の呼び出し以降に挿入が発生した場合、関数は overflow を呼び出します。 また、必要に応じて、ファイル変換ファセット fac を使用して fac.unshift を呼び出すことで、初期の変換状態を復元するために必要な任意のシーケンスも挿入します。 型 char の生成された各要素 byte は、ファイル ポインター fp によって指定された関連付けられているストリームに、フォーム fputc(byte, fp) の連続呼び出しのように書き込まれます。 fac.unshiftの呼び出しまたは書き込みに失敗した場合、関数は成功しません。

例

次の例は、現在のディレクトリ内の 2 つのファイル、basic_filebuf_close.txt (コンテンツは "testing") と iotest.txt (コンテンツは "ssss") を前提としています。

// basic_filebuf_close.cpp
// compile with: /EHsc
#include <fstream>
#include <iostream>

int main() {
   using namespace std;
   ifstream file;
   basic_ifstream <wchar_t> wfile;
   char c;
   // Open and close with a basic_filebuf
   file.rdbuf()->open( "basic_filebuf_close.txt", ios::in );
   file >> c;
   cout << c << endl;
   file.rdbuf( )->close( );

   // Open/close directly
   file.open( "iotest.txt" );
   file >> c;
   cout << c << endl;
   file.close( );

   // open a file with a wide character name
   wfile.open( L"iotest.txt" );

   // Open and close a nonexistent with a basic_filebuf
   file.rdbuf()->open( "ziotest.txt", ios::in );
   cout << file.fail() << endl;
   file.rdbuf( )->close( );

   // Open/close directly
   file.open( "ziotest.txt" );
   cout << file.fail() << endl;
   file.close( );
}

t
s
0
1

basic_filebuf::int_type

basic_filebuf スコープ内のこの型を、Tr スコープ内の同じ名前の型と同等にします。

typedef typename traits_type::int_type int_type;

basic_filebuf::is_open

ファイルが開いているかどうかを示します。

bool is_open() const;

戻り値

ファイル ポインターが Null でない場合は true。

例

// basic_filebuf_is_open.cpp
// compile with: /EHsc
#include <fstream>
#include <iostream>

int main( )
{
   using namespace std;
   ifstream file;
   cout << boolalpha << file.rdbuf( )->is_open( ) << endl;

   file.open( "basic_filebuf_is_open.cpp" );
   cout << file.rdbuf( )->is_open( ) << endl;
}

false
true

basic_filebuf::off_type

basic_filebuf スコープ内のこの型を、Tr スコープ内の同じ名前の型と同等にします。

typedef typename traits_type::off_type off_type;

basic_filebuf::open

ファイルを開きます。

basic_filebuf<Char_T, Tr> *open(
    const char* filename,
    ios_base::openmode mode,
    int protection = (int)ios_base::_Openprot);

basic_filebuf<Char_T, Tr> *open(
    const char* filename,
    ios_base::openmode mode);

basic_filebuf<Char_T, Tr> *open(
    const wchar_t* filename,
    ios_base::openmode mode,
    int protection = (int)ios_base::_Openprot);

basic_filebuf<Char_T, Tr> *open(
    const wchar_t* filename,
    ios_base::openmode mode);

パラメーター

filename
開くファイルの名前。

mode
ios_base::openmode の列挙体の 1 つ。

保護
_fsopen, _wfsopen の shflag パラメーターと同等の既定のファイル保護。

戻り値

バッファーが既に開いている場合、またはファイル ポインターが Null ポインターの場合、関数は Null ポインターを返します。 それ以外の場合は thisを返します。

解説

この関数では、FILE * を使用して、fopen/wfopen(filename, strmode) を呼び出した場合と同様に basic_filebuf を戻します。 strmode は、 mode & ~(ate | binary)から決定されます。

• ios_base::in は "r" になります (読み取り用に既存のファイルを開きます)。
• ios_base::out または ios_base::out | ios_base::trunc は "w" になります (既存のファイルを切り捨てるか、書き込み用に作成します)。
• ios_base::out | app は "a" になります (すべての書き込みを付加するために既存のファイルを開きます)。
• ios_base::in | ios_base::out は "r+" になります (読み取りと書き込み用に既存のファイルを開きます)。
• ios_base::in | ios_base::out | ios_base::trunc は "w+" になります (既存のファイルを切り捨てるか、読み取りと書き込み用に作成します)。
• ios_base::in | ios_base::out | ios_base::app は "a+" になります (読み取り用およびすべての書き込みを付加するために既存のファイルを開きます)。

mode & ios_base::binary が 0 以外の値の場合、関数は b を strmode に付加して、テキスト ストリームの代わりにバイナリ ストリームを開きます。 mode & ios_base::ateが 0 以外で、ファイルが正常に開かれた場合、ストリーム内の現在の場所はファイルの末尾に配置されます。 それが失敗した場合、ファイルは閉じられます。

上記の操作が正常に完了した場合は、underflow と overflow で使用するために、ファイル変換ファセットが決定されます。use_facet<codecvt<Char_T, char, traits_type::state_type> >(getloc)

ファイルを正常に開くことができない場合は、 nullptr が返されます。

例

open の使用例については、「basic_filebuf::close」を参照してください。

basic_filebuf::operator=

このストリーム バッファー オブジェクトの内容を割り当てます。 これは、右辺値が関係する移動代入で、コピーを残しません。

basic_filebuf& operator=(basic_filebuf&& right);

パラメーター

right
basic_filebuf オブジェクトへの右辺値参照。

戻り値

*this を返します。

解説

メンバー演算子により、右辺値の参照として扱われる right の内容を使用して、オブジェクトの内容が置き換えられます。 詳細については、「右辺値参照宣言子: &&」を参照してください。

basic_filebuf::overflow

いっぱいのバッファーに新しい文字が挿入されたときに呼び出されます。

virtual int_type overflow(int_type _Meta = traits_type::eof);

パラメーター

_Meta
バッファーに挿入する文字または traits_type::eof。

戻り値

関数が失敗すると、traits_type::eof を返します。 それ以外の場合は traits_type::not_eof(_Meta)を返します。

解説

_Meta != traits_type::eof の場合、プロテクト仮想メンバー関数は要素 ch = traits_type::to_char_type(_Meta) を出力バッファーに挿入しようとします。 これはさまざまな方法で行うことができます。

• 書き込み位置が使用可能な場合は、書き込み位置に要素を格納し、出力バッファーの次のポインターをインクリメントできます。

• 新しい記憶域または追加の記憶域を出力バッファーに割り当てることで、書き込み位置を使用可能にすることができます。

• ch の後に、必要に応じて、ファイル変換ファセット fac を使用して fac.out を呼び出すことで、出力バッファーで任意の保留中の出力を変換できます。 型 char の生成された各要素 ch は、ファイル ポインター fp によって指定された関連付けられているストリームに、フォーム fputc(ch, fp) の連続呼び出しのように書き込まれます。 変換または書き込みに失敗した場合、関数は成功しません。

basic_filebuf::p backfail

要素を入力ストリームに戻そうと試み、その要素を現在の要素に (ネクスト ポインターによって指されるように) します。

virtual int_type pbackfail(int_type _Meta = traits_type::eof);

パラメーター

_Meta
バッファーに挿入する文字または traits_type::eof。

戻り値

関数が失敗すると、traits_type::eof を返します。 それ以外の場合は traits_type::not_eof(_Meta)を返します。

解説

プロテクト仮想メンバー関数は要素を入力バッファーに戻してから、その要素を現在の要素に (ネクスト ポインターによって指されるように) します。 _Meta == traits_type::eof の場合、プッシュ バックする要素は、実質的に、現在の要素の前に既にストリームにある要素になります。 それ以外の場合、この要素は ch = traits_type::to_char_type(_Meta) によって置き換えられます。 この関数は、さまざまな方法で要素を戻すことができます。

• putback 位置が使用可能であり、格納されている要素が ch に等しい場合、入力バッファーのネクスト ポインターをデクリメントできます。

• 関数が putback 位置を使用可能にできる場合はそのようにし、ネクスト ポインターをその位置を指すように設定し、ch をその位置に格納します。

• 関数が入力ストリームに要素をプッシュバックできる場合は、char型の要素に対してungetcを呼び出すなどして、これを行うことができます。

basic_filebuf::p os_type

basic_filebuf スコープ内のこの型を、Tr スコープ内の同じ名前の型と同等にします。

typedef typename traits_type::pos_type pos_type;

basic_filebuf::seekoff

制御されているストリームの現在の位置を変更しようと試みます。

virtual pos_type seekoff(
    off_type _Off,
    ios_base::seekdir _Way,
    ios_base::openmode _Which = ios_base::in | ios_base::out);

パラメーター

_Off
シークする _Way の相対位置。

_Way
オフセット演算の開始位置。 有効値については、「seekdir」を参照してください。

_Which
ポインター位置のモードを指定します。 既定では、読み取り位置および書き込み位置を変更できます。

戻り値

新しい位置または無効なストリーム位置を返します。

解説

プロテクト仮想メンバー関数が、制御されているストリームの現在の位置を変更しようと試みます。 クラス basic_filebuf<Char_T, Tr> のオブジェクトの場合、ストリームの位置は、型 fpos_t のオブジェクトで表現できます。これにはオフセットと、ワイド ストリームを解析するために必要なすべての状態情報が格納されます。 オフセット 0 は、ストリームの最初の要素を参照します。 (型 pos_type のオブジェクトは、少なくとも fpos_t オブジェクトを格納します)。

読み取りと書き込みのために開かれたファイルの場合、入力と出力の両方のストリームが直列に配置されます。 挿入と抽出を切り替えるには、pubseekoff または pubseekpos のいずれかを呼び出す必要があります。 pubseekoff (および seekoff) への呼び出しには、テキスト ストリーム、バイナリ ストリーム、およびワイド ストリーム に対するさまざまな制限があります。

ファイル ポインター fp が Null ポインターの場合、関数は失敗します。 それ以外の場合、関数は fseek(fp, _Off, _Way) を呼び出してストリームの位置を変更しようとします。 その関数が成功し、fgetpos(fp, &fposn) を呼び出すことによって結果の位置 fposn を決定できる場合に、関数は成功します。 関数が成功すると、fposn を含む型 pos_type の値が返されます。 それ以外の場合は、無効なストリームの位置が返されます。

basic_filebuf::seekpos

制御されているストリームの現在の位置を変更しようと試みます。

virtual pos_type seekpos(
    pos_type _Sp,
    ios_base::openmode _Which = ios_base::in | ios_base::out);

パラメーター

_Sp
シークする位置。

_Which
ポインター位置のモードを指定します。 既定では、読み取り位置および書き込み位置を変更できます。

戻り値

ファイル ポインター fp が Null ポインターの場合、関数は失敗します。 それ以外の場合、関数は fsetpos(fp, &fposn) を呼び出してストリームの位置を変更しようとします。ここで、fposn は、pos に格納される fpos_t オブジェクトです。 その関数が成功すると、関数は pos を返します。 それ以外の場合は、無効なストリームの位置が返されます。 ストリームの位置が無効であることを確認するには、戻り値と pos_type(off_type(-1)) を比較します。

解説

プロテクト仮想メンバー関数が、制御されているストリームの現在の位置を変更しようと試みます。 クラス basic_filebuf<Char_T, Tr> のオブジェクトの場合、ストリームの位置は、型 fpos_t のオブジェクトで表現できます。これにはオフセットと、ワイド ストリームを解析するために必要なすべての状態情報が格納されます。 オフセット 0 は、ストリームの最初の要素を参照します。 (型 pos_type のオブジェクトは、少なくとも fpos_t オブジェクトを格納します)。

読み取りと書き込みのために開かれたファイルの場合、入力と出力の両方のストリームが直列に配置されます。 挿入と抽出を切り替えるには、pubseekoff または pubseekpos のいずれかを呼び出す必要があります。 pubseekoff (および seekoff) への呼び出しには、テキスト ストリーム、バイナリ ストリーム、およびワイド ストリームに対するさまざまな制限があります。

ワイド ストリームの場合、ストリームが開いてから、または streampos への最後の呼び出し以降に挿入が発生した場合、関数は overflow を呼び出します。 また、必要に応じて、ファイル変換ファセット fac を使用して fac.unshift を呼び出すことで、初期の変換状態を復元するために必要な任意のシーケンスも挿入します。 型 char の生成された各要素 byte は、ファイル ポインター fp によって指定された関連付けられているストリームに、フォーム fputc(byte, fp) の連続呼び出しのように書き込まれます。 fac.unshiftの呼び出しまたは書き込みに失敗した場合、関数は成功しません。

basic_filebuf::setbuf

各派生ストリーム バッファーに固有の操作を実行します。

virtual basic_streambuf<Char_T, Tr> *setbuf(
    char_type* _Buffer,
    streamsize count);

パラメーター

_Buffer
バッファーへのポインター。

count
バッファーのサイズ。

戻り値

プロテクト メンバー関数は、ファイル ポインター fp が Null ポインターの場合に、0 を返します。

解説

setbuf は setvbuf( fp, (char*) _Buffer, _IOFBF, count * sizeof( Char_T)) を呼び出して、_Buffer で始まる count 要素の配列をストリームのバッファーとして提供します。 その関数がゼロ以外の値を返す場合、関数は Null ポインターを返します。 それ以外の場合は、シグナルの成功に this を返します。

basic_filebuf::swap

この basic_filebuf の内容を、指定された basic_filebuf の内容と交換します。

void swap(basic_filebuf& right);

パラメーター

right
別の basic_filebuf への左辺値参照。

basic_filebuf::sync

制御されているストリームと、関連付けられている外部ストリームとを同期しようと試みます。

virtual int sync();

戻り値

ファイル ポインター fp が Null ポインターの場合、0 を返します。 それ以外の場合は、保留中の出力のストリームへのフラッシュで、overflow と fflush(fp) の両方の呼び出しが成功した場合にのみ 0 を返します。

basic_filebuf::traits_type

型名を Tr テンプレート パラメーターに関連付けます。

typedef Tr traits_type;

basic_filebuf::underflow

入力ストリームから現在の要素を抽出します。

virtual int_type underflow();

戻り値

関数が失敗すると、traits_type::eof を返します。 それ以外の場合、「注釈」セクションに記載されているように変換された ch が返されます。

解説

プロテクト仮想メンバー関数は、現在の要素 ch を入力ストリームから抽出して、要素を traits_type::to_int_type(ch) として返そうとします。 これはさまざまな方法で行うことができます。

• 読み取り位置が使用可能な場合は、読み取り位置に格納されている要素として ch を使用し、入力バッファーのネクスト ポインターを進めます。

• これは型 charの 1 つ以上の要素をフォーム fgetc(fp) の連続した呼び出しのように読み取り、必要に応じてファイル変換ファセット fac を使用して fac.in を呼び出して、型 Char_T の要素 ch に変換できます。 読み取りまたは変換に失敗した場合、関数は成功しません。

関連項目

<fstream>
C++ 標準ライブラリ内のスレッド セーフ
iostream プログラミング
iostreams の規則