KAI C++ Standard Class Libraries: Input/Output Library

Input/Output Library

Table of Contents	Algorithms	Iterators	Numerics
	Containers	Language Support	Strings
	Diagnostics	Localization	Utilities
Index	Input/Output

Stream buffers

Files

#include <streambuf.h>: The header <streambuf> defines types that control input from and output to character sequences.

Stream buffer requirements

Stream buffers can impose various constraints on the sequences they control Some constraints are

The controlled input sequence can be not readable.

The controlled output sequence can be not writable.

The controlled sequences can be associated with the contents of other representations for character sequences, such as external files.

The controlled sequences can support operations directly to or from associated sequences.

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.

Each sequence is characterized by three pointers which, if non-null, all point into the same charT array object. The array object represents, at any moment, a (sub)sequence of characters from the sequence. Operations performed on a sequence alter the values stored in 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 subsequence relationship. The three pointers are:

the beginning pointer, or lowest element address in the array (called xbeg here).

the next pointer, or next element address that is a current candidate for reading or writing(called xnext here).

the end pointer, or first element address beyond the end of the array (called xend here).

The following semantic constraints shall always apply for any set of three pointers for a sequence, using the pointer names given immediately above:

If xnext is not a null pointer, then xbeg and xend shall also be non-null pointers into the same charT array, as described above.

If xnext is not a null pointer and xnext<xend for an output sequence, then a write position is available. In this case, *xnext shall be assignable as the next element to write(to put, or to store a character value, into the sequence).

If xnext is not a null pointer and xbeg<xnext for an input sequence, then a putback position is available. In this case, xnext[-1] shall have a defined value and is the next(preceding) element to store a character that is put back into the input sequence.

IF xnext is not a null pointer and xnext < xend for an input sequence, then a read position is available. In this case, *xnext shall have a defined value and is the next element to read(to get, or to obtain a character value, from the sequence).

Template class basic_streambuf<charT,traits>

The class template basic_streambuf<charT,traits> serves as an abstract base class for deriving various stream buffers whose objects each control two character sequences:

a character input sequence, called the get area;

a character output sequence, called the put area.

Two specializations of this class has to be provided by the implementation. The class streambuf which is an instantiation of the template class basic_streambuf specialized by the type char.The class wstreambuf which is an instantiation of the template class basic_streambuf specialized by the type wchar_t.

Private data members

The private data members of this class basic_streambuf are implementation dependent. This implementation of the class has six pointers. They are:

the beginning pointer for the get area, or lowest element address in the array (called gbeg here).

the next pointer for the get area, or next element address that is a current candidate for reading (called gnext here).

the end pointer for the get area, or first element address beyond the end of the array (called gend here).

the beginning pointer for the put area, or lowest element address in the array (called pbeg here).

the next pointer for the put area, or next element address that is a current candidate for writing (called pnext here).

the end pointer for the put area, or first element address beyond the end of the array (called pend here).

basic_streambuf constructors

basic_streambuf();: This function is a protected member for class basic_streambuf to assure that only objects for classes derived from this class may be constructed. It constructs an object of class basic_streambuf<charT, traits> and initializes all its pointer member objects to null pointers and the getloc() member to return value of locale::classic().

basic_streambuf public member functions

Locales

locale pubimbue(const locale& loc);

This function calls imbue(loc) and resets the basic_streambuf<charT, traits>::locvariable. It returns the previous value of basic_streambuf<charT, traits>::loc.

locale getloc() const;: If pubimbue() has ever been called, then the last value of loc supplied, otherwise classic "C" locale locale::classic(). If called after pubimbue() has been called but before pubimbue() has returned(i.e from within the call of imbue()) then it returns the previous value.

Buffer management and positioning

basic_streambuf<char_type,traits>*

pubsetbuf(char_type* s, streamsize n);

This function returns setbuf(s,n).

pos_type pubseekoff(off_type off, ios_base::seekdir way, ios_base::openmode which=

ios_base::in | ios_base::out);

This function returns seekoff(off,way, which).

pos_type pubseekpos(pos_type sp, ios_base::openmode which = ios_base::in |

ios_base::out) This function returns seekpos(sp, which).

int pubsync();

This function returns sync().

Get area

streamsize in_avail();: If a read position is available, returns number of characters that can be read. Otherwise returns showmanyc().
int_type snextc();: This function increments the next pointer for the input sequence(gnext) and then returns the value pointed to by this pointer.
int_type sbumpc();: If the input sequence read position is not available, returns uflow(). Otherwise, returns char_type(*gptr()) and increments the next pointer for the input sequence(gnext), so that it points to the next character in the input stream.
int_type sgetc();: If the input sequence read position is not available, returns underflow(). Otherwise, returns char_type(*gptr()). This function does not increment the next pointer for the input sequence(gnext).
streamsize sgetn(char_type* s, streamsize n);: This function returns xsgetn(s,n).

Putback

int_type sputbackc(char_type c);: If the input sequence putback position is not available (i.e gnext and gbeg are pointing to the same position), or if c!=gptr()[-1], returns pbackfail(c). Otherwise, decrements the next pointer for the input sequence(gnext) and returns *gptr().
int_type sungetc();: If the input sequence putback position is not available (i.e gnext and gbeg are pointing to the same position), returns pbackfail(). Otherwise, decrements the next pointer for the input sequence(gnext) and returns *gptr().

Put area

int_type sputc(char_type c);: If the output sequence write position is not available(i.e pnext and pend are pointing to the same position), returns overflow(c). Otherwise, stores c at the next pointer for the output sequence(pnext), increments the pointer, and returns *pptr().
int_type sputn(const char_type* s, streamsize n);: This function returns xsputn(s, n).

basic_streambuf protected member functions

Get area access

char_type* eback() const;: This function returns the beginning pointer(gbeg) for the input sequence.
char_type* gptr() const;: This function returns the next pointer(gnext) for the input sequence.
char_type* egptr() const;: This function returns the end pointer(gend) for the input sequence.
void gbump(int n);: This function advances the next pointer(gnext) for the input sequence by n.
void setg(char_type* gbeg, char_type* gnext, char_type* gend);: This function sets the value for the private data members gbeg, gnext and gend from the arguments passed to it.

Put area access

char_type* pbase() const;: This function returns the beginning pointer for the output sequence(pbeg).
char_type* pptr() const;: This function returns the next pointer for the output sequence(pnext).
char_type* epptr() const;: This function returns the end pointer for the output sequence(pend).
void pbump(int n);: This function advances the next pointer(pnext) for the output sequence by n.
void setg(char_type* pbeg, char_type* pnext, char_type* pend);: This function sets the value of pointers pbeg, pnext and pend from the arguments passed to it.

basic_streambuf virtual functions

Locales

void imbue(const locale&);: This function allows the derived class to be informed of changes in locale at the time they occur. Between invocations of this function a class derived from streambuf can safely cache results of calls to locale functions and to members of facets so obtained.

Buffer management and positioning

basic_streambuf* setbuf(char_type* s, streamsize n);: This function does nothing but has to be defined by the derived classed. It returns this.
pos_type seekoff(off_type off, ios_base::seekdir way, ios_base::openmode which =: ios_base::in | ios_base::out);

This function 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. It returns an object of class pos_type that stores an invalid stream position(pos_type(-1)) by default.

pos_type seekpos(pos_type sp, ios_base::openmode which= in| out);

This function 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 in this clause. It returns an object of class pos_type that stores an invalid stream position.

int sync();

This function synchronizes the controlled sequences with the array. That is, if pbase() is non-null the cahracters between pbase() and pptr() are written to the controlled sequence, and if gptr() is non-null, the characters between gptr() and egptr() are restored to the input sequence. The pointers may then be reset appropriately. It returns -1 on failure and 0 by default.

Get area

int showmanyc();

This function returns a guaranteed lower bound on the number of characters that can be read from the input sequence before a call to uflow() or underflow() returns traits::eof(). A positive return value indicates that the next such call will not return traits::eof(). It returns zero by default.

streamsize xsgetn(char_type* s, streamsize n);

This function assigns up to n characters to successive elements of the array whose first element is designated by s. The characters assigned are read from the input sequence as if by repeated calls to sbumpc(). Assigning stops when either n characters have been assigned or a call to sbumpc() would return traits::eof(). It returns the number of characters assigned.

int_type underflow();

This function returns the first character of the pending sequence, if possible, without moving the input sequence position past it. If the pending sequence is null then the function fails. The public members of basic_streambuf call this virtual function only if gptr() is null or gptr()>=egptr().

The pending sequence of characters is defined as the concatenation of:

If gptr() is non-NULL, then the egptr()-gptr() characters starting at gptr(), otherwise the empty sequence.

Some sequence(possibly empty) of characters read from the input sequence.

The result character is

If the pending sequence is non-empty, the first character of the sequence.

If the pending sequence empty then the next character that would be read from the input sequence.

The backup sequence is defined as the concatenation of:

If eback() is null then empty.

Otherwise the gptr()-eback() characters beginning at eback().

The function sets up the gptr() and egptr() satisfying one of:

If the pending sequence is non-empty, egptr() is non-null and egptr()-gptr() characters starting at gptr() are the characters in the pending sequence.

If the pending sequence is empty, either gptr() is null or gptr() and egptr() are set to the same non-NULL pointer.

If eback() and gptr() are non-null then the function is not constrained as to their contents, but the usual backup condition is that either:

IF the backup sequence contains at least gptr()-eback() characters, then the gptr()-eback() characters starting at eback() agree with the last gptr()-eback() characters of the backup sequence.

Or the n characters starting at gptr()-n agree with the backup sequence(where n is the length of the backup sequence).

int_type uflow();

The constraints for this function are the same as for underflow(), except that the result character is transferred from the pending sequence to the backup sequence, and the pending sequence may not be empty before the transfer.

This function on default calls underflow(traits::eof()). If underflow() returns traits::eof() returns traits::eof(). Otherwise, does gbump(-1) and returns *gptr().

Putback

int_type pbackfail(int c=traits::eof());

The public functions of basic_streambuf call this virtual function only when gptr() is null, gptr()==eback(), or *gptr()!=c. Other calls shall also satisfy that constraint.The pending sequence is defined as for underflow(), with the modifications that

If c==traits::eof() then the input sequence is backed up one character before the pending sequence is determined.

If c!=traits::eof() then c is prepended. Whether the input sequence is backed up or modified in any other way is unspecified.

This function returns traits::eof() to indicate failure. Failure may occur because the input sequence could not be backed up, or if for some other reason the pointers could not be set consistent with the constraints. This function is called only when put back has really failed. It returns some value other than traits::eof() to indicate success.

Put area

streamsize xsputn(const char_type* s, streamsize n);

This function writes up to n characters to the output sequence as if by repeated calls to sputc(c). 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(c) would return traits::eof(). This function returns the number of characters written.

int_type overflow(int_type c=traits::eof());

This function consumes some initial subsequence of the characters of the pending sequence. The pending sequence is defined as the concatenation of

if pbase() is NULL then the empty sequence otherwise, pptr()-pbase() characters beginning at pbase().

if c==traits::eof() then the empty sequence otherwise, the sequence consisting of c.

The member functions sputc() and sputn() call this function in case that no room can be found in the put buffer enough to accommodate the argument character sequence.

This function requires every overriding definition of this virtual function shall obey the following constraints:

The effect of consuming a character on the associated output sequence is specified.
Let r be the number of characters in the pending sequence not consumed. If r is non-zero then pbase() and pptr() must be set so that: pptr() - pbase()==r and the r characters starting at pbase() are the associated output stream. In case r is zero(all characters of the pending sequence have been consumed) then either pbase() is set NULL, or pbase() and pptr() are both set to the same non-NULL value.
The function may fail if either appending some character to the associated output stream fails or if it is unable to establish pbase() and pptr() according to the above rules.
This function returns traits::eof() of throws an exception if the function fails. Otherwise, returns some value other than traits::eof() to indicate success.

E-Mail KAI Technical Support E-Mail KAI Contact KAI

This file last updated on May 17, 1996.