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>
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...........
Constructors
Constructs an object of type basic_filebuf. |
Typedefs
Associates a type name with the Elem template parameter. |
|
Makes this type within basic_filebuf's scope equivalent to the type of the same name in the Tr scope. |
|
Makes this type within basic_filebuf's scope equivalent to the type of the same name in the Tr scope. |
|
Makes this type within basic_filebuf's scope equivalent to the type of the same name in the Tr scope. |
|
Associates a type name with the Tr template parameter. |
Member Functions
Closes a file. |
|
Indicates whether a file is open. |
|
Opens a file. |
|
A protected virtual function that can be called when a new character is inserted into a full buffer. |
|
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). |
|
The protected virtual member function tries to alter the current positions for the controlled streams. |
|
The protected virtual member function tries to alter the current positions for the controlled streams. |
|
The protected virtual member function performs an operation particular to each derived stream buffer. |
|
Exchanges the content of this basic_filebuf for the content of the provided basic_filebuf parameter. |
|
Protected, virtual function tries to synchronize the controlled streams with any associated external streams. |
|
Protected, virtual function to extract the current element from the input stream. |
|
Protected, virtual function to extract the current element from the input stream. |
Requirements
Header: <fstream>
Namespace: std