|
|
basic_filebuf , basic_fstream , basic_ifstream , basic_ofstream , filebuf , fstream , ifstream , ofstream , wfilebuf , wfstream , wifstream , wofstream - defines several iostreams template classes that manipulate exteral files
namespace std { template<class E, class T = char_traits<E> > class basic_filebuf; typedef basic_filebuf<char> filebuf; typedef basic_filebuf<wchar_t> wfilebuf; template<class E, class T = char_traits<E> > class basic_ifstream; typedef basic_ifstream<char> ifstream; typedef basic_ifstream<wchar_t> wifstream; template<class E, class T = char_traits<E> > class basic_ofstream; typedef basic_ofstream<char> ofstream; typedef basic_ofstream<wchar_t> wofstream; template<class E, class T = char_traits<E> > class basic_fstream; typedef basic_fstream<char> fstream; typedef basic_fstream<wchar_t> wfstream; };
Include the iostreams
standard header <fstream>
to define several classes that support
iostreams operations on
sequences stored in external
files.
basic_filebuf , close , is_open , open , overflow , pbackfail , seekoff , seekpos , setbuf , sync , underflow
template <class E, class T = char_traits<E> > class basic_filebuf : public basic_streambuf<E, T> { public: typedef typename basic_streambuf<E, T>::char_type char_type; typedef typename basic_streambuf<E, T>::traits_type traits_type; typedef typename basic_streambuf<E, T>::int_type int_type; typedef typename basic_streambuf<E, T>::pos_type pos_type; typedef typename basic_streambuf<E, T>::off_type off_type; basic_filebuf(); bool is_open() const; basic_filebuf *open(const char *s, ios_base::openmode mode); basic_filebuf *close(); protected: virtual pos_type seekoff(off_type off, ios_base::seekdir way, ios_base::openmode which = ios_base::in | ios_base::out); virtual pos_type seekpos(pos_type pos, ios_base::openmode which = ios_base::in | ios_base::out); virtual int_type underflow(); virtual int_type pbackfail(int_type c = traits_type::eof()); virtual int_type overflow(int_type c = traits_type::eof()); virtual int sync(); virtual basic_streambuf<E, T> *setbuf(E *s, streamsize n); };
The template class
describes a stream buffer that controls
the transmission of elements
of type E
, whose
character traits are determined by the
class T
,
to and from a sequence of elements stored in an external
file.
An object of class
basic_filebuf<E, T>
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
.
basic_filebuf();
The constructor stores a null pointer in all the pointers controlling the input buffer and the output buffer. It also stores a null pointer in the file pointer.
typedef E char_type;
The type is a synonym for the template parameter E
.
basic_filebuf *close();
The member function returns a null pointer if the
file pointer fp
is a null pointer. Otherwise, it calls
fclose(fp)
.
If that function returns a nonzero value, the function
returns a null pointer. Otherwise, it returns this
to indicate that the file was successfully
closed.
For a wide stream,
if any insertions have occured since the stream was opened, or since the last
call to streampos
, the function calls
overflow()
.
It also inserts any sequence needed to restore the
initial conversion state,
by using the
file conversion facet
fac
to call
fac.unshift
as needed. Each element x
of type char thus
produced is written to the associated stream designated by the
file pointer fp
as if by successive calls of the form
fputc(x, fp)
.
If the call to fac.unshift
or any write fails,
the function does not succeed.
typedef typename traits_type::int_type int_type;
The type is a synonym for
traits_type::int_type
.
bool is_open();
The member function returns true if the file pointer is not a null pointer.
typedef typename traits_type::off_type off_type;
The type is a synonym for
traits_type::off_type
.
basic_filebuf *open(const char *s, ios_base::openmode mode);
The member function endeavors to open the file with
filename s
, by calling
fopen(s, strmode)
. Here
strmode
is determined from mode &
~(ate & |
binary)
:
ios_base::in
becomes "r"
(open existing file for reading).ios_base::out
or
ios_base::out |
ios_base::trunc
becomes "w"
(truncate existing file or create for writing).ios_base::out |
app
becomes "a"
(open existing file for appending all writes).ios_base::in | ios_base::out
becomes "r+"
(open existing file for reading and writing).ios_base::in | ios_base::out |
ios_base::trunc
becomes "w+"
(truncate existing file or create for reading and writing).ios_base::in | ios_base::out |
ios_base::app
becomes "a+"
(open existing file for reading and for appending all writes).If mode & ios_base::binary
is nonzero,
the function appends b
to strmode
to open a binary stream
instead of a text stream.
It then stores the value returned by fopen
in the
file pointer fp
. If
mode & ios_base::ate
is nonzero and the
file pointer is not a null pointer, the function calls
fseek(fp, 0,
SEEK_END)
to
position the stream at end-of-file. If that positioning operation
fails, the function calls
close(fp)
and
stores a null pointer in the file pointer.
If the file pointer is not a null pointer, the function
determines the
file conversion facet:
use_facet<
codecvt<E, char,
traits_type::
state_type>
>(getloc())
,
for use by
underflow
and
overflow
.
If the file pointer is a null pointer, the function returns
a null pointer. Otherwise, it returns this
.
virtual int_type overflow(int_type c = traits_type::eof());
If c !=
traits_type::eof()
,
the protected virtual member function endeavors to insert the element
traits_type::to_char_type(c)
into the
output buffer.
It can do so in various ways:
c
, by using the
file conversion facet
fac
to call
fac.out
as needed. Each element x
of type char thus
produced is written to the associated stream designated by the
file pointer fp
as if by successive calls of the form
fputc(x, fp)
.
If any conversion or write fails, the function does not succeed.If the function cannot succeed, it returns traits_type::eof()
.
Otherwise, it returns
traits_type::not_eof(c)
.
virtual int_type pbackfail(int_type c = traits_type::eof());
The protected virtual member function endeavors to put back an element
into the
input buffer,
then make it the current element (pointed to
by the next pointer). If c ==
traits_type::eof()
,
the element to push back is effectively the one already in the stream
before the current element. Otherwise, that element is replaced by
x =
traits_type::to_char_type(c)
.
The function can put back an element in various ways:
x
,
it can simply decrement the next pointer for the input buffer.x
in that position.ungetc
for an element
of type char.If the function cannot succeed, it returns
traits_type::eof()
. Otherwise, it returns
traits_type::not_eof(c)
.
typedef typename traits_type::pos_type pos_type;
The type is a synonym for
traits_type::pos_type
.
virtual pos_type seekoff(off_type off, ios_base::seekdir way, ios_base::openmode which = ios_base::in | ios_base::out);
The protected virtual member function endeavors to alter the current
positions for the controlled streams. For an object of class
basic_filebuf<E, T>
, a stream position can be represented
by an object of type
fpos_t
, which stores an
offset and any state information needed to parse a
wide stream.
Offset zero designates the first element of the stream.
(An object of type
pos_type
stores at least an fpos_t
object.)
For a file opened for both reading and writing,
both the input and output streams are positioned in tandem. To
switch
between inserting and extracting, you must call either
pubseekoff
or
pubseekpos
.
Calls to pubseekoff
(and hence to seekoff
)
have various limitations for
text streams,
binary streams, and
wide streams.
If the
file pointer fp
is a null pointer, the function fails. Otherwise, it endeavors
to alter the stream position by calling
fseek(fp, off, way)
.
If that function succeeds and the resultant position
fposn
can be determined by calling
fgetpos(fp, &fposn)
,
the function succeeds. If the function succeeds, it returns
a value of type pos_type
containing fposn
.
Otherwise, it returns an invalid stream position.
virtual pos_type seekpos(pos_type pos, ios_base::openmode which = ios_base::in | ios_base::out);
The protected virtual member function endeavors to alter the current
positions for the controlled streams. For an object of class
basic_filebuf<E, T>
, a stream position can be represented
by an object of type
fpos_t
, which stores an
offset and any state information needed to parse a
wide stream.
Offset zero designates the first element of the stream.
(An object of type
pos_type
stores at least an fpos_t
object.)
For a file opened for both reading and writing,
both the input and output streams are positioned in tandem. To
switch
between inserting and extracting, you must call either
pubseekoff
or
pubseekpos
.
Calls to pubseekoff
(and hence to seekoff
)
have various limitations for
text streams,
binary streams, and
wide streams.
For a wide stream,
if any insertions have occured since the stream was opened, or since the last
call to streampos
, the function calls
overflow()
.
It also inserts any sequence needed to restore the
initial conversion state,
by using the
file conversion facet
fac
to call
fac.unshift
as needed. Each element x
of type char thus
produced is written to the associated stream designated by the
file pointer fp
as if by successive calls of the form
fputc(x, fp)
.
If the call to fac.unshift
or any write fails,
the function does not succeed.
If the
file pointer fp
is a null pointer, the function fails. Otherwise, it endeavors
to alter the stream position by calling
fsetpos(fp, &fposn)
,
where fposn
is the fpos_t
object stored
in pos
. If that function succeeds, the function returns
pos
. Otherwise, it returns an invalid stream position.
virtual basic_streambuf<E, T> *setbuf(E *s, streamsize n);
The protected member function returns zero if the
file pointer fp
is a null pointer. Otherwise, it calls
setvbuf(fp, (char *)s,
_IOFBF, n * sizeof (E))
to offer the array of n
elements beginning at s
as a buffer for the stream. If that function returns a nonzero value,
the function returns a null pointer. Otherwise, it returns this
to signal success.
int sync();
The protected member function returns zero if the
file pointer fp
is a null pointer. Otherwise, it returns zero only if calls to both
overflow()
and
fflush(fp)
succeed in flushing any pending output to the stream.
typedef T traits_type;
The type is a synonym for the template parameter T
.
virtual int_type underflow();
The protected virtual member function endeavors to extract the current
element c
from the input stream, and return the element as
traits_type::to_int_type(c)
.
It can do so in various ways:
c
as the element stored in the read position
and advances the next pointer for the
input buffer.
fgetc(fp)
,
and convert them to an element c
of type E
by using the
file conversion facet
fac
to call
fac.in
as needed.
If any read or conversion fails,
the function does not succeed.If the function cannot succeed, it returns
traits_type::eof()
. Otherwise,
it returns c
, converted as described above.
basic_fstream , basic_fstream , close , is_open , open , rdbuf
template <class E, class T = char_traits<E> > class basic_fstream : public basic_iostream<E, T> { public: basic_fstream(); explicit basic_fstream(const char *s, ios_base::openmode mode = ios_base::in | ios_base::out); basic_filebuf<E, T> *rdbuf() const; bool is_open() const; void open(const char *s, ios_base::openmode mode = ios_base::in | ios_base::out); void close(); };
The template class describes an object that controls
insertion and extraction of elements and encoded objects using a
stream buffer of class
basic_filebuf<E, T>
,
with elements of type E
, whose
character traits are determined
by the class T
. The object stores an object of class
basic_filebuf<E, T>
.
basic_fstream(); explicit basic_fstream(const char *s, ios_base::openmode mode = ios_base::in | ios_base::out);
The first constructor initializes the base class by calling
basic_iostream(sb)
,
where sb
is the stored object of class
basic_filebuf<E, T>
.
It also initializes sb
by calling
basic_filebuf<E,
T>()
.
The second constructor initializes the base class by calling
basic_iostream(sb)
.
It also initializes sb
by calling
basic_filebuf<E,
T>()
,
then sb.open(s, mode)
.
If the latter function returns a null pointer, the constructor calls
setstate(failbit)
.
voidclose();
The member function calls
rdbuf()->
close()
.
bool is_open();
The member function returns
rdbuf()->
is_open()
.
void open(const char *s, ios_base::openmode mode = ios_base::in | ios_base::out);
The member function calls
rdbuf()->
open(s, mode)
.
If that function returns a null pointer, the function calls
setstate(failbit)
.
basic_filebuf<E, T> *rdbuf() const
The member function returns the address of the stored
stream buffer, of type pointer to
basic_filebuf<E, T>
.
basic_ifstream , basic_ifstream , close , is_open , open , rdbuf
template <class E, class T = char_traits<E> > class basic_ifstream : public basic_istream<E, T> { public: basic_filebuf<E, T> *rdbuf() const; basic_ifstream(); explicit basic_ifstream(const char *s, ios_base::openmode mode = ios_base::in); bool is_open() const; void open(const char *s, ios_base::openmode mode = ios_base::in); void close(); };
The template class describes an object that controls
extraction of elements and encoded objects from a
stream buffer of class
basic_filebuf<E, T>
,
with elements of type E
, whose
character traits are determined
by the class T
. The object stores an object of class
basic_filebuf<E, T>
.
basic_ifstream(); explicit basic_ifstream(const char *s, ios_base::openmode mode = ios_base::in);
The first constructor initializes the base class by calling
basic_istream(sb)
,
where sb
is the stored object of class
basic_filebuf<E, T>
.
It also initializes sb
by calling
basic_filebuf<E,
T>()
.
The second constructor initializes the base class by calling
basic_istream(sb)
.
It also initializes sb
by calling
basic_filebuf<E, T>()
,
then sb.open(s, mode
| ios_base::in)
. If the latter function returns a null
pointer, the constructor calls
setstate(failbit)
.
void close();
The member function calls
rdbuf()->
close()
.
bool is_open();
The member function returns
rdbuf()->
is_open()
.
void open(const char *s, ios_base::openmode mode = ios_base::in);
The member function calls
rdbuf()->
open(s, mode | ios_base::in)
.
If that function returns a null pointer, the function calls
setstate(failbit)
.
basic_filebuf<E, T> *rdbuf() const
The member function returns the address of the stored stream buffer.
basic_ofstream , basic_ofstream , close , is_open , open , rdbuf
template <class E, class T = char_traits<E> > class basic_ofstream : public basic_ostream<E, T> { public: basic_filebuf<E, T> *rdbuf() const; basic_ofstream(); explicit basic_ofstream(const char *s, ios_base::openmode mode = ios_base::out); bool is_open() const; void open(const char *s, ios_base::openmode mode = ios_base::out); void close(); };
The template class describes an object that controls
insertion of elements and encoded objects into a
stream buffer of class
basic_filebuf<E, T>
,
with elements of type E
, whose
character traits are determined
by the class T
. The object stores an object of class
basic_filebuf<E, T>
.
basic_ofstream(); explicit basic_ofstream(const char *s, ios_base::openmode which = ios_base::out);
The first constructor initializes the base class by calling
basic_ostream(sb)
,
where sb
is the stored object of class
basic_filebuf<E, T>
.
It also initializes sb
by calling
basic_filebuf<E, T>()
.
The second constructor initializes the base class by calling
basic_ostream(sb)
.
It also initializes sb
by calling
basic_filebuf<E, T>()
,
then sb.open(s, mode
| ios_base::out)
. If the latter function returns a null
pointer, the constructor calls
setstate(failbit)
.
void close();
The member function calls
rdbuf()->
close()
.
bool is_open();
The member function returns
rdbuf()->
is_open()
.
void open(const char *s, ios_base::openmode mode = ios_base::out);
The member function calls
rdbuf()->
open(s, mode | ios_base::out)
.
If that function returns a null pointer, the function calls
setstate(failbit)
.
basic_filebuf<E, T> *rdbuf() const
The member function returns the address of the stored stream buffer.
typedef basic_filebuf<char, char_traits<char> > filebuf;
The type is a synonym for template class
basic_filebuf
, specialized
for elements of type char with default
character traits.
typedef basic_fstream<char, char_traits<char> > fstream;
The type is a synonym for template class
basic_fstream
, specialized
for elements of type char with default
character traits.
typedef basic_ifstream<char, char_traits<char> > ifstream;
The type is a synonym for template class
basic_ifstream
, specialized
for elements of type char with default
character traits.
typedef basic_ofstream<char, char_traits<char> > ofstream;
The type is a synonym for template class
basic_ofstream
, specialized
for elements of type char with default
character traits.
typedef basic_fstream<wchar_t, char_traits<wchar_t> > wfstream;
The type is a synonym for template class
basic_fstream
, specialized
for elements of type wchar_t
with default
character traits.
typedef basic_ifstream<wchar_t, char_traits<wchar_t> > wifstream;
The type is a synonym for template class
basic_ifstream
, specialized
for elements of type wchar_t
with default
character traits.
typedef basic_ofstream<wchar_t, char_traits<wchar_t> > wofstream;
The type is a synonym for template class
basic_ofstream
, specialized
for elements of type wchar_t
with default
character traits.
typedef basic_filebuf<wchar_t, char_traits<wchar_t> > wfilebuf;
The type is a synonym for template class
basic_filebuf
, specialized
for elements of type wchar_t
with default
character traits.
Copyright © 1992-1996 by P.J. Plauger. Portions derived from work copyright © 1994 by Hewlett-Packard Company. All rights reserved.