<streambuf>namespace std {
template<class E, class T = char_traits<E> >
class basic_streambuf;
typedef basic_streambuf<char, char_traits<char> >
streambuf;
typedef basic_streambuf<wchar_t,
char_traits<wchar_t> > wstreambuf;
};
Include the iostreams
standard header <streambuf> to define
template class basic_streambuf,
which is basic to the operation of the iostreams classes. (This
header is typically included for you by another of the iostreams
headers. You seldom have occasion to include it directly.)
basic_streambufbasic_streambuf
· char_type
· eback · egptr
· epptr · gbump
· getloc · gptr
· imbue · in_avail ·
int_type ·
off_type ·
overflow ·
pbackfail
· pbase · pbump
· pos_type ·
pptr
· pubimbue ·
pubseekoff
· pubseekpos
· pubsetbuf
· pubsync · sbumpc
· seekoff · seekpos
· setbuf · setg
· setp · sgetc
· sgetn · showmanyc
· snextc · sputbackc
· sputc · sputn
· sungetc · sync
· traits_type
· uflow · underflow
· xsgetn · xsputn
template <class E, class T = char_traits<E> >
class basic_streambuf {
public:
typedef E char_type;
typedef T traits_type;
typedef typename traits_type::int_type int_type;
typedef typename traits_type::pos_type pos_type;
typedef typename traits_type::off_type off_type;
virtual ~streambuf();
locale pubimbue(const locale& loc);
locale getloc() const;
basic_streambuf *pubsetbuf(char_type *s,
streamsize n);
pos_type pubseekoff(off_type off,
ios_base::seekdir way,
ios_base::openmode which =
ios_base::in | ios_base::out);
pos_type pubseekpos(pos_type sp,
ios_base::openmode which =
ios_base::in | ios_base::out);
int pubsync();
streamsize in_avail();
int_type snextc();
int_type sbumpc();
int_type sgetc();
streamsize sgetn(char_type *s, streamsize n);
int_type sputbackc(char_type c);
int_type sungetc();
int_type sputc(char_type c);
streamsize sputn(const char_type *s, streamsize n);
protected:
basic_streambuf();
char_type *eback() const;
char_type *gptr() const;
char_type *egptr() const;
void gbump(int n);
void setg(char_type *gbeg,
char_type *gnext, char_type *gend);
char_type *pbase() const;
char_type *pptr() const;
char_type *epptr() const;
void pbump(int n);
void setp(char_type *pbeg, char_type *pend);
virtual void imbue(const locale &loc);
virtual basic_streambuf *setbuf(char_type *s,
streamsize n);
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 sp,
ios_base::openmode which =
ios_base::in | ios_base::out);
virtual int sync();
virtual streamsize showmanyc();
virtual streamsize xsgetn(char_type *s,
streamsize n);
virtual int_type underflow();
virtual int_type uflow();
virtual int_type pbackfail(int_type c =
traits_type::eof());
virtual streamsize xsputn(const char_type *s,
streamsize n);
virtual int_type overflow(int_type c =
traits_type::eof());
};
The template class describes an abstract base class for
deriving a stream buffer,
which controls the transmission of elements to and from a
specific representation of a stream. An object of class basic_streambuf
helps control a stream with elements of type T, also
known as char_type,
whose character traits
are determined by the class char_traits, also known
as traits_type.
Every stream buffer conceptually controls two independent
streams, in fact, one for extractions (input) and one for
insertions (output). A specific representation may, however, make
either or both of these streams inaccessible. It typically
maintains some relationship between the two streams. What you
insert into the output stream of a basic_stringbuf<E,
T> object, for example, is what you later extract from
its input stream. And when you position one stream of a basic_filebuf<E, T>
object, you position the other stream in tandem.
The public interface to template class basic_streambuf
supplies the operations common to all stream buffers, however
specialized. The protected interface supplies the operations
needed for a specific representation of a stream to do its work.
The protected virtual member functions let you tailor the
behavior of a derived stream buffer for a specific representation
of a stream. Each of the derived stream buffers in this library
describes how it specializes the behavior of its protected
virtual member functions. Documented here is the default
behavior for the base class, which is often to do nothing.
The remaining protected member functions control copying to and from any storage supplied to buffer transmissions to and from streams. An input buffer, for example, is characterized by:
eback(),
a pointer to the beginning of the buffer gptr(),
a pointer to the next element to read egptr(),
a pointer just past the end of the buffer Similarly, an output buffer is characterized by:
pbase(),
a pointer to the beginning of the buffer pptr(),
a pointer to the next element to write epptr(),
a pointer just past the end of the buffer For any buffer, the protocol is:
Any protected virtual member functions you write for a class
derived from basic_streambuf<E, T> must
cooperate in maintaining this protocol.
An object of class basic_streambuf<E, T>
stores the six pointers described above. It also stores a locale object in an
object of type locale
for potential use by a derived stream buffer.
basic_streambuf::basic_streambufbasic_streambuf();
The protected constructor stores a null pointer in all the
pointers controlling the input buffer and the output
buffer. It also stores locale::classic() in the locale object.
basic_streambuf::char_typetypedef E char_type;
The type is a synonym for the template parameter E.
basic_streambuf::ebackchar_type *eback() const;
The member function returns a pointer to the beginning of the input buffer.
basic_streambuf::egptrchar_type *egptr() const;
The member function returns a pointer just past the end of the input buffer.
basic_streambuf::epptrchar_type *epptr() const;
The member function returns a pointer just past the end of the output buffer.
basic_streambuf::gbumpvoid gbump(int n);
The member function adds n to the next pointer
for the input
buffer.
basic_streambuf::getloclocale getloc() const;
The member function returns the stored locale object.
basic_streambuf::gptrchar_type *gptr() const;
The member function returns a pointer to the next element of the input buffer.
basic_streambuf::imbuevirtual void imbue(const locale &loc);
The default behavior is to do nothing.
basic_streambuf::in_availstreamsize in_avail();
If a read
position is available, the member function returns egptr()
- gptr().
Otherwise, it returns showmanyc().
basic_streambuf::int_typetypedef typename traits_type::int_type int_type;
The type is a synonym for traits_type::int_type.
basic_streambuf::off_typetypedef typename traits_type::off_type off_type;
The type is a synonym for traits_type::off_type.
basic_streambuf::overflowvirtual int_type overflow(int_type c =
traits_type::eof());
If c does not compare equal to traits_type::eof(), the
protected virtual member function endeavors to insert the element
traits_type::to_char_type(c)
into the output stream. It can do so in various ways:
If the function cannot succeed, it returns traits_type::eof()
or throws an exception. Otherwise, it returns Otherwise, it
returns traits_type::not_eof(c).
The default behavior is to return traits_type::eof().
basic_streambuf::pbackfailvirtual int_type pbackfail(int_type c =
traits_type::eof());
The protected virtual member function endeavors to put back an
element into the input stream, then make it the current element
(pointed to by the next pointer). If c compares
equal to 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 traits_type::to_char_type(c).
The function can put back an element in various ways:
If the function cannot succeed, it returns traits_type::eof()
or throws an exception. Otherwise, it returns some other value.
The default behavior is to return traits_type::eof().
basic_streambuf::pbasechar_type *pbase() const;
The member function returns a pointer to the beginning of the output buffer.
basic_streambuf::pbumpvoid pbump(int n);
The member function adds n to the next pointer
for the output
buffer.
basic_streambuf::pos_typetypedef typename traits_type::pos_type pos_type;
The type is a synonym for traits_type::pos_type.
basic_streambuf::pptrchar_type *pptr() const;
The member function returns a pointer to the next element of the output buffer.
basic_streambuf::pubimbuelocale pubimbue(const locale& loc);
The member function stores loc in the locale
object, calls imbue(),
then returns the previous value stored in the locale object.
basic_streambuf::pubseekoffpos_type pubseekoff(off_type off,
ios_base::seekdir way,
ios_base::openmode which =
ios_base::in | ios_base::out);
The member function returns seekoff(off,
way, which).
basic_streambuf::pubseekpospos_type pubseekpos(pos_type sp,
ios_base::openmode which =
ios_base::in | ios_base::out);
The member function returns seekpos(sp,
which).
basic_streambuf::pubsetbufbasic_streambuf *pubsetbuf(char_type *s, streamsize n);
The member function returns stbuf(s, n).
basic_streambuf::pubsyncint pubsync();
The member function returns sync().
basic_streambuf::sbumpcint_type sbumpc();
If a read
position is available, the member function returns traits_type::to_int_type( *gptr())
and increments the next pointer for the input buffer. Otherwise,
it returns uflow().
basic_streambuf::seekoffvirtual 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. The new position is determined as follows:
way == ios_base::beg,
the new position is the beginning of the stream plus off.
way == ios_base::cur,
the new position is the current stream position plus off.
way == ios_base::end,
the new position is the end of the stream plus off.
Typically, if which & ios_base::in is
nonzero, the input stream is affected, and if which &
ios_base::out is nonzero, the output stream is affected.
Actual use of this parameter varies among derived stream buffers,
however.
If the function succeeds in altering the stream position(s), it returns the resultant stream position (or one of them). Otherwise, it returns an invalid stream position. The default behavior is to return an invalid stream position.
basic_streambuf::seekposvirtual pos_type seekpos(pos_type sp,
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. The new position is
sp.
Typically, if which & ios_base::in is
nonzero, the input stream is affected, and if which &
ios_base::out is nonzero, the output stream is affected.
Actual use of this parameter varies among derived stream buffers,
however.
If the function succeeds in altering the stream position(s), it returns the resultant stream position (or one of them). Otherwise, it returns an invalid stream position. The default behavior is to return an invalid stream position.
basic_streambuf::setbufvirtual basic_streambuf *setbuf(char_type *s,
streamsize n);
The protected virtual member function performs an operation
peculiar to each derived stream buffer. (See, for example, basic_filebuf.) The
default behavior is to return this.
basic_streambuf::setgvoid setg(char_type *gbeg, char_type *gnext,
char_type *gend);
The member function stores gbeg in the beginning
pointer, gnext in the next pointer, and gend
in the end pointer for the input buffer.
basic_streambuf::setpvoid setp(char_type *pbeg, char_type *pend);
The member function stores pbeg in the beginning
pointer, pbeg in the next pointer, and pend
in the end pointer for the output buffer.
basic_streambuf::sgetcint_type sgetc();
If a read
position is available, the member function returns traits_type::to_int_type( *gptr())
Otherwise, it returns underflow().
basic_streambuf::sgetnstreamsize sgetn(char_type *s, streamsize n);
The member function returns xsgetn(s, n).
basic_streambuf::showmanycvirtual streamsize showmanyc();
The protected virtual member function returns a count of the number of characters that can be extracted from the input stream with no fear that the program will suffer an indefinite wait. The default behavior is to return zero.
basic_streambuf::snextcint_type snextc();
The member function calls sbumpc()
and, if that function returns traits_type::eof(), returns traits_type::eof().
Otherwise, it returns sgetc().
basic_streambuf::sputbackcint_type sputbackc(char_type c);
If a putback position is
available and c compares equal to the character
stored in that position, the member function decrements the next
pointer for the input buffer and returns
ch, which is the value traits_type::to_int_type(c).
Otherwise, it returns pbackfail(ch).
basic_streambuf::sputcint_type sputc(char_type c);
If a write position is
available, the member function stores c in the write
position, increments the next pointer for the output buffer, and
returns ch, which is the value traits_type::to_int_type(c).
Otherwise, it returns overflow(ch).
basic_streambuf::sputnstreamsize sputn(const char_type *s, streamsize n);
The member function returns xsputn(s, n).
basic_streambuf::sungetcint_type sungetc();
If a putback position is
available, the member function decrements the next pointer for
the input
buffer and returns traits_type::to_int_type( *gptr()).
Otherwise it returns pbackfail().
basic_streambuf::syncvirtual int sync();
The protected virtual member function endeavors to synchronize the controlled streams with any associated external streams. Typically, this involves writing out any elements between the beginning and next pointers for the output buffer. It does not involve putting back any elements between the next and end pointers for the input buffer. If the function cannot succeed, it returns -1. The default behavior is to return zero.
basic_streambuf::traits_typetypedef T traits_type;
The type is a synonym for the template parameter T.
basic_streambuf::uflowvirtual int_type uflow();
The protected virtual member function endeavors to extract the
current element c from the input stream, then
advance the current stream position, 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. c. If the function cannot succeed, it returns traits_type::eof(), or throws
an exception. Otherwise, it returns the current element c
in the input stream, converted as described above, and advances
the next pointer for the input buffer. The default behavior is to
call underflow()
and, if that function returns traits_type::eof(), to
return traits_type::eof(). Otherwise, the function
returns the current element c in the input stream,
converted as described above, and advances the next pointer for
the input buffer.
basic_streambuf::underflowvirtual int_type underflow();
The protected virtual member function endeavors to extract the
current element c from the input stream, without
advancing the current stream position, and return it as traits_type::to_int_type(c).
It can do so in various ways:
c is the element stored in the
read position. If the function cannot succeed, it returns traits_type::eof(), or throws
an exception. Otherwise, it returns the current element in the
input stream, converted as described above. The default behavior
is to return traits_type::eof().
basic_streambuf::xsgetnvirtual streamsize xsgetn(char_type *s, streamsize n);
The protected virtual member function extracts up to n
elements from the input stream, as if by repeated calls to sbumpc,
and stores them in the array beginning at s. It
returns the number of elements actually extracted.
basic_streambuf::xsputnvirtual streamsize xsputn(const char_type *s,
streamsize n);
The protected virtual member function inserts up to n
elements into the output stream, as if by repeated calls to sputc,
from the array beginning at s. It returns the number
of elements actually inserted.
streambuftypedef basic_streambuf<char, char_traits<char> >
streambuf;
The type is a synonym for template class basic_streambuf,
specialized for elements of type char with default character traits.
wstreambuftypedef basic_streambuf<wchar_t, char_traits<wchar_t> >
wstreambuf;
The type is a synonym for template class basic_streambuf,
specialized for elements of type wchar_t with
default character traits.
See also the Table of Contents .
Copyright © 1992-1996 by P.J. Plauger. All rights reserved.