Export (0) Print
Expand All

basic_filebuf Class

Describes a stream buffer that controls the transmission of elements of type Elem, whose character traits are determined by the class Tr, to and from a sequence of elements stored in an external file.

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

Elem

The basic element of the file buffer.

Tr

The traits of the basic element of the file buffer (usually char_traits<Elem>).

The template class describes a stream buffer that controls the transmission of elements of type Elem, whose character traits are determined by the class Tr, to and from a sequence of elements stored in an external file.

Note Note

Objects of type basic_filebuf are created with an internal buffer of type char * regardless of the char_type specified by the type parameter Elem. This means that a Unicode string (containing wchar_t characters) will be converted to an ANSI string (containing char characters) before it is written to the internal buffer. To store Unicode strings in the buffer, create a new buffer of type wchar_t and set it using the basic_streambuf::pubsetbuf() method. To see an example that demonstrates this behavior, see below.

An object of class basic_filebuf<Elem, Tr> stores a file pointer, which designates the FILE object that controls the stream associated with an open file. It also stores pointers to two file conversion facets for use by the protected member functions overflow and underflow. For more information, see basic_filebuf::open.

The following example demonstrates how to force an object of type basic_filebuf<wchar_t> to store Unicode characters in its internal buffer by calling the pubsetbuf() method.

// 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

Constructs an object of type basic_filebuf.

char_type

Associates a type name with the Elem template parameter.

int_type

Makes this type within basic_filebuf's scope equivalent to the type of the same name in the Tr scope.

off_type

Makes this type within basic_filebuf's scope equivalent to the type of the same name in the Tr scope.

pos_type

Makes this type within basic_filebuf's scope equivalent to the type of the same name in the Tr scope.

traits_type

Associates a type name with the Tr template parameter.

close

Closes a file.

is_open

Indicates whether a file is open.

open

Opens a file.

overflow

A protected virtual function that can be called when a new character is inserted into a full buffer.

pbackfail

The protected virtual member function tries to put back an element into the input stream, then make it the current element (pointed to by the next pointer).

seekoff

The protected virtual member function tries to alter the current positions for the controlled streams.

seekpos

The protected virtual member function tries to alter the current positions for the controlled streams.

setbuf

The protected virtual member function performs an operation particular to each derived stream buffer.

Swap

Exchanges the content of this basic_filebuf for the content of the provided basic_filebuf parameter.

sync

Protected, virtual function tries to synchronize the controlled streams with any associated external streams.

uflow

Protected, virtual function to extract the current element from the input stream.

underflow

Protected, virtual function to extract the current element from the input stream.

Header: <fstream>

Namespace: std

Show:
© 2014 Microsoft