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.
For a list of all members of this type, see basic_filebuf Members.
template <class Elem, class Tr = char_traits<Elem> >
class basic_filebuf : public basic_streambuf<Elem, Tr>
Parameters
Elem
The basic element of the file buffer.Tr
The traits of the basic element of the file buffer (usually char_traits<Elem>).
Remarks
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
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.
Example
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...........
Requirements
Header: <fstream>
Namespace: std
See Also
Reference
Thread Safety in the Standard C++ Library