Standard C++ Library
Copyright 1998, Rogue Wave Software, Inc.
NAME
basic_streambuf, streambuf, wstreambuf
- Abstract base class for deriving various stream buffers
to facilitate control of character sequences.
SYNOPSIS
#include <streambuf>
template<class charT, class traits = char_traits<charT> >
class basic_streambuf;
DESCRIPTION
The class template basic_streambuf<charT,traits> serves as
an abstract base class for deriving various stream buffers
to facilitate control of character sequences such as:
o A character input sequence;
o A character output sequence.
Each sequence is associated with three pointers (as
described below), which, if non-null, all point into the
same charT array object. The array object represents, at any
moment, a segment of characters from the sequence. Opera-
tions performed on a sequence alter the values pointed to by
these pointers, perform reads and writes directly to or from
associated sequences, and alter "the stream position" and
conversion state as needed to maintain this segment to
sequence relationship. The three pointers are:
o The beginning pointer, or lowest element address in the
array;
o The next pointer, or next element address that is a
current candidate for reading or writing;
o The end pointer, or first element address beyond the
end of the array.
Stream buffers can impose various constraints on the
sequences they control, including:
o The controlled input sequence may be unreadable;
o The controlled output sequence may be unwriteable;
o The controlled sequences can be associated with the
contents of other representations for character
sequences, such as external files;
o The controlled sequences can impose limitations on how
the program can read characters from a sequence, write
characters to a sequence, put characters back into an
input sequence, or alter the stream position.
INTERFACE
template<class charT, class traits = char_traits<charT> >
class basic_streambuf {
public:
typedef charT char_type;
typedef traits traits_type;
typedef typename traits::int_type int_type;
typedef typename traits::pos_type pos_type;
typedef typename traits::off_type off_type;
virtual ~basic_streambuf();
locale pubimbue( const locale& loc);
locale getloc() const;
basic_streambuf<char_type, traits> *
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();
ios_base::openmode which_open_mode();
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 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_arg,char_type *gnext_arg,
char_type *gend_arg);
char_type *pbase() const;
char_type *pptr() const;
char_type *epptr() const;
void pbump(int n);
void setp(char_type *pbeg_arg,char_type *pend_arg);
virtual void imbue( const locale& loc);
virtual basic_streambuf<charT, traits>*
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 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::eof());
virtual streamsize xsputn(const char_type *s,
streamsize n);
virtual int_type overflow(int_type c = traits::eof());
virtual int sync();
};
TYPES
char_type
The type char_type is a synonym for the template parame-
ter charT.
int_type
The type int_type is a synonym of type traits::in_type.
off_type
The type off_type is a synonym of type traits::off_type.
pos_type
The type pos_type is a synonym of type traits::pos_type.
streambuf
The type streambuf is an instantiation of class
basic_streambuf on type char:
typedef basic_streambuf<char> streambuf;
traits_type
The type traits_type is a synonym for the template param-
eter traits.
wstreambuf
The type wstreambuf is an instantiation of class
basic_streambuf on type wchar_t:
typedef basic_streambuf<wchar_t> wstreambuf;
PUBLIC CONSTRUCTORS
basic_streambuf();
Constructs an object of class basic_streambuf. Initial-
izes all its pointer member objects to null pointers, and
initializes the getloc() member function to return the
value of locale::locale().
PUBLIC DESTRUCTORS
virtual ~basic_streambuf();
Destroys an object of class basic_streambuf.
PUBLIC MEMBER FUNCTIONS
locale
getloc() const;
If pubimbue() has ever been called, returns the last
value of loc supplied. Otherwise, it returns the default
(global) locale locale::locale() in effect at the time of
construction.
streamsize
in_avail();
If a read position is available, returns the number of
available characters in the input sequence. Otherwise
calls the protected function showmanyc().
locale
pubimbue(const locale& loc);
Calls the protected function imbue(loc).
pos_type
pubseekoff(off_type off, ios_base::seekdir way,
ios_base::openmode which =
ios_base::in | ios_base::out );
Calls the protected function seekoff(off,way,which).
pos_type
pubseekpos(pos_type sp, ios_base::openmode which=
ios_base::in | ios_base::out );
Calls the protected function seekpos(sp,which).
basic_streambuf<char_type,traits>*
pubsetbuf(char_type* s,streamsize n);
Calls the protected function setbuf(s,n) .
int
pubsync();
Calls the protected function sync().
int_type
sbumpc();
If the input sequence read position is not available,
calls the function uflow(). Otherwise it returns *gptr()
and increments the next pointer for the input sequence.
int_type
sgetc();
If the input sequence read position is not available,
calls the protected function underflow(). Otherwise it
returns *gptr().
streamsize
sgetn(char_type* s, streamsize n);
Calls the protected function xsgetn(s,n).
int_type
snextc();
Calls the function sbumpc() and if it returns
traits::eof(), returns traits::eof(). Otherwise it calls
the function sgetc().
int_type
sputbackc(char_type c);
If the input sequence putback position is not available
or if traits::eq(c,gptr() [-1]) returns false, calls the
protected function pbackfail(c). Otherwise it decrements
the next pointer for the input sequence and returns
*gptr().
int_type
sputc(char_type c);
If the output sequence write position is not available,
calls the protected function
overflow(traits::to_int_type( c )). Otherwise, it stores
c at the next pointer for the output sequence, increments
the pointer, and returns *pptr().
streamsize
sputn(const char_type* s, streamsize n);
Calls the protected function xsputn(s,n).
int_type
sungetc();
If the input sequence putback position is not available,
calls the protected function pbackfail(). Otherwise it
decrements the next pointer for the input sequence and
returns *gptr().
ios_base::openmode
which_open_mode();
Returns the mode in which the stream buffer is opened.
This function is not described in the C++ standard.
PROTECTED MEMBER FUNCTIONS
char_type*
eback() const;
Returns the beginning pointer for the input sequence.
char_type*
egptr() const;
Returns the end pointer for the input sequence.
char_type*
epptr() const;
Returns the end pointer for the output sequence.
void
gbump(int n);
Advances the next pointer for the input sequence by n.
char_type*
gptr() const;
Returns the next pointer for the input sequence.
void
imbue(const locale&);
Changes any translations based on locale. The default
behavior is to do nothing. This function has to be over-
loaded in the classes derived from basic_streambuf. The
purpose of this function is to allow the derived class to
be informed of changes in locale at the time they occur.
The new imbued locale object is only used by the stream
buffer; it does not affect the stream itself.
int_type
overflow(int_type c = traits::eof() );
The member functions sputc() and sputn() call this func-
tion when not enough room can be found in the put buffer
to accommodate the argument character sequence. The func-
tion returns traits::eof() if it fails to make more room
available or if it fails to empty the buffer by writing
the characters to their output device.
int_type
pbackfail(int_type c = traits::eof() );
If c is equal to traits::eof(), gptr() is moved back one
position. Otherwise c is prepended. The function returns
traits::eof() to indicate failure.
char_type*
pbase() const;
Returns the beginning pointer for the output sequence.
void
pbump(int n);
Advances the next pointer for the output sequence by n.
char_type*
pptr() const;
Returns the next pointer for the output sequence.
pos_type
seekoff(off_type off, ios_base::seekdir way,
ios_base::openmode which =
ios_base::in | ios_base::out );
Alters the stream positions within one or more of the
controlled sequences in a way that is defined separately
for each class derived from basic_streambuf. The default
behavior is to return an object of type pos_type that
stores an invalid stream position.
pos_type
seekpos(pos_type sp, ios_base::openmode which=
ios_base::in | ios_base::out );
Alters the stream positions within one or more of the
controlled sequences in a way that is defined separately
for each class derived from basic_streambuf. The default
behavior is to return an object of class pos_type that
stores an invalid stream position.
basic_streambuf*
setbuf(char_type* s, streamsize n);
Performs an operation that is defined separately for each
class derived from basic_streambuf. The purpose of this
function is to allow the user to provide his own buffer
or to resize the current buffer.
void
setg(char_type* gbeg, char_type* gnext, char_type* gend);
Sets up a private member for the following to be true:
eback() == gbeg, gptr() == gnext and egptr() == gend
void
setp(char_type* pbeg, char_type* pend);
Sets up a private member for the following to be true:
pbase() == pbeg, pptr() == pbeg and epptr() == pend
int
showmanyc();
Returns the number of characters available in the inter-
nal buffer, or returns -1.
int
sync();
Synchronizes the controlled sequences with the internal
buffer, in a way that is defined separately for each
class derived from basic_streambuf. The default behavior
is to do nothing. On failure the return value is -1.
int_type
underflow();
The public members of basic_streambuf call this function
only if gptr() is null or gptr() >= egptr(). This func-
tion returns the character pointed to by gptr(), if
gptr() is not null and if gptr() < egptr(). Otherwise the
function tries to read character into the buffer. If it
fails, it returns traits::eof().
int_type
uflow();
Calls underflow() and if underflow() returns
traits::eof(), returns traits::eof(). Otherwise, does
gbump(1) and returns the value of *gptr().
streamsize
xsgetn(char_type* s, streamsize n);
Assigns up to n characters to successive elements of the
array whose first element is designated by s. The charac-
ters are read from the input sequence. Assigning stops
when either n characters have been assigned or a call to
sbumpc() would return traits::eof(). The function returns
the number of characters read.
streamsize
xsputn(const char_type* s, streamsize n);
Writes up to n characters to the output sequence. The
characters written are obtained from successive elements
of the array whose first element is designated by s.
Writing stops when either n characters have been written
or a call to sputc() would return traits::eof(). The
function returns the number of characters written.
SEE ALSO
char_traits(3C++), basic_filebuf(3C++),
basic_stringbuf(3C++), strstreambuf(3C++)
Working Paper for Draft Proposed International Standard for
Information Systems--Programming Language C++, Section
27.5.2
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee