basic_streambuf class template — Stream buffer
template <class charT, class traits = char_traits<charT> > class basic_streambuf{ public: typedef charT char_type; typedef typename traits::int_type int_type; typedef typename traits::pos_type pos_type; typedef typename traits::off_type off_type; typedef traits traits_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 pubseekoff(off_type off, ios_base::seekdir way, ios_base::open_mode which=ios_base::in | ios_base::out); pos_type pubseekpos(pos_type sp, ios_base::openmode which = ios_base::in | ios_base::out); pos_type pubseekpos(pos_type sp,ios_base::open_mode which); int pubsync( ); // Input streamsize in_avail( ); int_type snextc( ); int_type sbumpc( ); int_type stossc( ); int_type sgetc( ); streamsize sgetn(char_type* s, streamsize n); // Putback int_type sputbackc(char_type c); int_type sungetc( ); // Output int_type sputc(char_type c); streamsize sputn(const char_type* s, streamsize n); protected: basic_streambuf( ); // Input 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); // Output char_type* pbase( ) const; char_type* pptr( ) const; char_type* epptr( ) const; void pbump(int n); void setp(char_type* pbeg, char_type* pend); // Locales virtual void imbue(const locale &loc); // Buffer management and positioning virtual basic_streambuf<char_type,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 streamsize showmanyc( ); virtual int sync( ); virtual int_type underflow( ); virtual int_type uflow( ); virtual streamsize xsgetn(char_type* s, streamsize n); // Putback virtual int_type pbackfail(int_type c = traits::eof( )); // Output virtual int_type overflow(int_type c = traits::eof( )); virtual streamsize xsputn(const char_type* s, streamsize n); };
The basic_streambuf
class
template manages an input buffer and an output buffer, in which each
buffer is an array of characters. The base character type is a
template parameter, charT
. A
buffer has the following three pointers to the array (the names
below are not part of the standard but are used for informational
purposes only):
begin
Points to the beginning of the array
next
Points to the next element in the array, that is, the next character to read or the position at which to write the next character
end
Points to one past the end of the array
The pointers in this list can all be null pointers, which makes the stream "buffer" unbuffered. If the pointers are not null, the following rules apply:
If next
<
end
for an output array,
the stream buffer is said to have a write
position. The next output character is
written to *
next
.
If begin
<
next
for an input array,
the stream buffer is said to have a push
back position. When a character
is pushed back, it is stored in next
[-1]
.
If next
<
end
for an input array, the
stream buffer is said to have a read
position. The next character to read from
the buffer is *
next
.
Figure 13-25 depicts an input buffer, in which the characters "Hello, world." have been fetched from the input source. So far, the first six characters have been read from the input buffer, and the next character to read is the space between "Hello," and "world."
Figure 13-26 depicts an output buffer, which has room for 12 characters. So far, the buffer contains the five characters "Hello".
Several functions come in pairs: a public function that is the
public interface and a protected, virtual function to do the actual
work. For example, pubsync
is a
public function that simply calls sync
, which is protected and virtual. The
name of the public function is pub
followed by the name of the protected
function. The two exceptions are sgetn
and sputn
, which are public, with xsgetn
and xsputn
as their protected
counterparts.
The basic_streambuf
class
template implements minimal functionality for managing the buffer
pointers. Derived-class templates must override the virtual
functions to provide concrete behavior. See basic_filebuf
in <fstream>
, basic_stringbuf
in <sstream>
, and strstreambuf
in <strstream>
for examples of derived
classes and templates.
The following descriptions start with the expected public
behavior. If you are writing a stream class that uses a stream
buffer, you can rely on that behavior from the stream buffer object.
If you are writing your own derived-class template, that is the
behavior you must implement. Each description ends with the actual
implementation in basic_streambuf
.
When comparing characters, converting characters to integers
or integers to characters, and obtaining the end-of-file marker,
basic_streambuf
uses the
character traits specified by the traits
template parameter. See <string>
for information about the
default character traits, char_traits
.
The following are the public member functions of basic_streambuf
:
locale
getloc
( )
const
Returns the current locale, which can be set by calling
pubimbue
.
streamsize
in_avail
( )
Returns the number of characters available for input.
The return value is egptr(
)
- gptr( )
if
the stream buffer has a read position, or the result of
calling showmanyc( )
if the
stream buffer does not have a read position.
locale
pubimbue
(const locale
&loc)
Saves a copy of the locale, loc
. Subsequent calls to getloc
return a copy of the imbued
locale. The basic_streambuf
class does not use the locale, but a derived class can use the
locale to interpret multibyte characters and for other
purposes. When a stream buffer is created, it is initially
imbued with the global locale.
pos_type
pubseekoff
(off_type off,
ios_base::seekdir way, ios_base::openmode
which=ios_base::in|ios_base::out)
, pos_type
pubseekoff
(off_type off,
ios_base::seekdir way, ios_base::open_mode
which=ios_base::in|ios_base::out)
Returns seekoff(off
,
way
, which)
, which changes the stream
position. The second form is deprecated. See ios_base::openmode
in <ios>
for details.
pos_type
pubseekpos
(pos_type sp,
ios_base::openmode
which=ios_base::in|ios_base::out)
, pos_type
pubseekpos
(pos_type sp,
ios_base::open_mode which)
Returns seekpos(off
,
way
, which)
, which changes the stream
position. The second form is deprecated. See ios_base::openmode
in <ios>
for details.
basic_streambuf<char_type,traits>*
pubsetbuf
(char_type* s,
streamsize n)
Returns setbuf(s
,
n)
, which typically sets
the begin
, next
, and end
array pointers.
int
pubsync
( )
Returns sync( )
,
which synchronizes the internal arrays with the external I/O
source, if any. The pubsync
function returns -1
for a
failure and any other value for success.
int_type
snextc
( )
Returns the next input character and advances the input
pointers. Specifically, snextc
calls sbumpc( )
, and if sbumpc
returns traits::eof( )
, snextc
returns traits::eof( )
; otherwise, it
returns sgetc( )
.
int_type
sbumpc
( )
, int_type
stossc
( )
Returns the next input character (if one is available)
and increments the input array's next
pointer. If there is no read
position, sbumpc
returns
uflow( )
; otherwise, it
returns *gptr( )
.
The stossc
function is
deprecated. If it is implemented, it calls sbumpc( )
.
int_type
sgetc
( )
Returns the next available input character without
advancing the input pointer. If no read position is available,
sgetc
returns underflow( )
; otherwise, it returns
*gptr( )
.
streamsize
sgetn
(char_type* s,
streamsize n)
Returns xsgetn(s
,
n)
.
virtual streamsize
showmanyc
( )
Returns an estimate of the number of characters
immediately available for input. If showmanyc
returns a positive value,
at least that many characters can be read before underflow
returns traits::eof( )
. If showmanyc
returns -1
, calls to underflow
or uflow
will fail. If the return value
is 0
, input might be
available, but there is no guarantee. Read the function name
as s-how-many-c
.
int_type
sputbackc
(char_type
c)
Tries to push back the character c
so the next read will return
c
. If a push-back position
is available (gptr( )
>
ebase( )
), and the most recently
read character (gptr(
)[-1]
) is c
, the
input next
pointer is
decremented, and *gptr( )
is returned. Otherwise, pbackfail(c)
is returned.
int_type
sputc
(char_type
c)
Writes the character c
to the output array and returns
c
if an output position is
available. Otherwise, sputc
returns overflow(c)
.
streamsize
sputn
(const char_type* s,
streamsize n);
Calls xsputn(s
,
n)
to write a string
s
of length n
.
int_type
sungetc
( )
Pushes back the character that was read most recently
from the input stream. If a push-back position is available,
the function decrements the input next
pointer and returns *gptr( )
; otherwise, it returns
pbackfail( )
.
The following are the protected member functions of basic_streambuf
. Those marked as virtual
should probably be overridden in a
derived class template.
basic_streambuf
( )
Initializes all pointers to null pointers. The locale
(as returned from getloc(
)
) is initialized to the current global
locale.
char_type*
eback
( )
const
Returns the begin
pointer for the input array.
char_type*
egptr
( )
const
Returns the end
pointer for the input array.
char_type*
epptr
( )
const
Returns the end
pointer for the output array.
void
gbump
(int n)
Advances the next
pointer for the input array by n
characters.
char_type*
gptr
( )
const
Returns the next
pointer for the input array.
virtual void
imbue
(const locale
&loc)
A derived class overrides the imbue
function to take whatever
action is needed when the stream buffer's locale is changed.
For example, the stream buffer might cache facets or other
information from the new locale.
The pubimbue
function
calls imbue
before storing a new locale; thus, within
the call to imbue
, the
getloc
function returns the
old locale, and the loc
parameter is the new locale.
The default behavior for imbue
is to do nothing.
virtual int_type
overflow
(int_type c =
traits::eof( ))
The stream buffer calls overflow
to flush the output buffer
when it is full. The overflow
function handles the
sequence of characters stored in the buffer array, or an empty
string if the begin
and
other pointers are null. If c
is not traits::eof( )
, c
is appended to the output
sequence. For example, a file stream buffer might write the
array to the file. If an output error occurs, an exception is
thrown or traits::eof( )
is
returned. For success, any value other than traits::eof( )
is returned.
The default behavior is to do nothing and return
traits::eof( )
.
virtual int_type
pbackfail
(int_type c =
traits::eof( ))
Handles a push-back failure. When the sungetc
or sputbackc
functions try to push back
a character, they first attempt to adjust the current input
next
pointer. This can
fail for one of three reasons:
Input is unbuffered (gptr(
)
==
0
).
The input buffer is empty (gptr( )
==
eback( )
).
The push-back character, c
, is not the same character
that was most recently read (that is, c
!=
gptr( )[-1]
).
If the push-back attempt fails, pbackfail
mediates with the external
input source, if any, to try to complete the push-back
operation. For example, a file stream buffer might adjust the
external file position so the next character read from the
input array will retrieve the pushed-back character.
If c
is traits::eof( )
, the input sequence
is moved back one position to reread the character at that
position. If c
is not
traits::eof( )
, pbackfail
tries to ensure that the
next character read will be c
; the derived class is free to
modify the input source, change the stream position, or take
another action to push back c
.
The return value is traits::eof( )
for failure or any
other value for success.
The default behavior is to do nothing and return
traits::eof( )
.
char_type*
pbase
( )
const
Returns the output buffer's begin
pointer.
void
pbump
(int n)
Increments the output buffer's next
pointer by n
characters.
char_type*
pptr
( )
const
Returns the output buffer's next
pointer.
Virtual pos_type
seekoff
(off_type off,
ios_base::seekdir way, ios_base::openmode
which=ios_base::in|ios_base::out)
Changes the stream position. The default behavior is to
do nothing except return pos_type(-1)
.
virtual pos_type
seekpos
(pos_type sp,
ios_base::openmode
which=ios_base::in|ios_base::out)
Changes the stream position. The default behavior is to
do nothing except return pos_type(-1)
.
virtual
basic_streambuf<char_type,traits>*
setbuf
(char_type* s,
streamsize n)
Typically sets the internal array pointers. The default
behavior is to do nothing and return this
.
void
setg
(char_type* gbegin,
char_type* gnext, char_type* gend)
Sets the input array pointers: begin
= gbegin
, next
= gnext
, and end
= gend
.
void
setp
(char_type* pbegin,
char_type* pend)
Sets the output array pointers: begin
= next
= pbegin
and end
= pend
.
virtual int
sync
( )
Synchronizes the stream buffer with its external source,
if any. Any characters in the output array are written, and
all pointers are adjusted as needed. The return value is
-1
for failure and anything
else for success.
The default behavior is to do nothing and return
0
.
virtual int_type
uflow
( )
Fills the input array and fetches the first character
from the array. It is called from sbumpc
if the input is not buffered
(gptr( )
==
0
) or if the input buffer is empty
(gptr( )
>=
egptr( )
). Input is obtained from
the external source, and the input pointers are reset.
The key difference between uflow
and underflow
is that uflow
advances the input next
pointer after returning the
first character in the buffer, but underflow
does not.
The return value from uflow
is *gptr( )
if there is a read position
or traits::eof( )
if there
is no more input or some other failure occurs.
The default behavior is to do nothing and return
traits::eof( )
.
virtual int_type
underflow
( )
Fills the input array and returns the first character in
the array. The sgetc( )
function calls underflow
when the input is not buffered (gptr(
)
==
0
) or when the input buffer is empty
(gptr( )
>=
egptr( )
). Input is obtained from
the external source, and the input pointers are reset.
The key difference between uflow
and underflow
is that uflow
advances the input next
pointer after returning the
first character in the buffer, but underflow
does not.
The return value is *gptr(
)
if there is a read position or traits::eof( )
if there is no more
input or some other failure occurs.
The default behavior is to do nothing and return
traits::eof( )
.
virtual streamsize
xsgetn
(char_type* s,
streamsize n)
Reads up to n
characters from the input stream into the character array that
s
points to. No null
character is appended to s
.
It is equivalent to calling sbumpc
up to n
times or until it returns traits::eof( )
. The number of
characters actually read and stored in s
is returned. Derived classes can
override this function to provide a more efficient
implementation.
virtual streamsize
xsputn
(const char_type* s,
streamsize n)
Writes up to n
characters from s
to the
output stream. It is equivalent to calling sputc
up to n
times or until it returns traits::eof( )
. The number of
characters actually written is returned. Derived classes can
override this function to provide a more efficient
implementation.