Input/Output Classes

The input/output stream classes provide program access to the file system. In addition, various options for formatting of output and reading of input are provided.

The following diagram shows the hierarchy of the I/O classes:

fig: ./images/io_cls.gif

ios: the I/O state class
fstreambase: the base class for file I/O operations
istream: the class for input only
ostream: the class for output only
strstreambase: the base class for string I/O operations
iostream: the class for input and output
ifstream: the class for input only from a file
ofstream: the class for output only to a file
fstream: the class for input and output for files
istrstream: the class for input only from a string
ostrstream: the class for output only to a string
strstream: the class for input and output for strings

These classes are associated with the buffer classes shown below:

fig: ./images/buf_cls.gif

streambuf: The basic buffer class
filebuf: the file buffer class
stdiobuf: the buffer class for standard I/O
strstreambuf: the string buffer class

This chapter also discusses the manipulators that can be used to do such things as format input and output.

`filebuf` Class

The filebuf class is derived from the streambuf class, and provides additional functionality required to communicate with external files. Seek operations are supported when the underlying file supports seeking. Both input and output operations may be performed using a filebuf object, again when the underlying file supports read/write access.

filebuf objects are buffered by default, so the reserve area is allocated automatically, unless one is specified when the filebuf object is created. The get area and put area pointers operate as if they were tied together. There's only one current position in a filebuf object.

The filebuf class allows only the get area or the put area, but not both, to be active at a time. This follows from the capability of files opened for both reading and writing to have operations of each type performed at arbitrary locations in the file:

When writing is occurring, the characters are buffered in the put area. If a seek or read operation is done, the put area must be flushed before the next operation, in order to ensure that the characters are written to the proper location in the file.
Similarly, if reading is occurring, characters are buffered in the get area. If a write operation is done, the get area must be flushed and synchronized before the write operation, in order to ensure the write occurs at the proper location in the file. If a seek operation is done, the get area doesn't have to be synchronized, but is discarded.

When the get area is empty and a read is done, the underflow() virtual member function reads more characters and fills the get area again. When the put area is full and a write is done, the overflow() virtual member function writes the characters and makes the put area empty again.

C++ programmers who wish to use files without deriving new objects don't need to explicitly create or use a filebuf object.

Public Data Members

The following data member is declared in the public interface. Its value is the default file protection that's used when creating new files. It's primarily referenced as a default argument in member functions.

static int const openprot;

Public Member Functions

The following member functions are declared in the public interface:

filebuf();
filebuf( filedesc );
filebuf( filedesc, char *, int );
~filebuf();
int is_open() const;
filedesc fd() const;
filebuf *attach( filedesc );
filebuf *open( char const *,
           ios::openmode,
           int = filebuf::openprot );
filebuf *close();
virtual int pbackfail( int );
virtual int overflow( int = EOF );
virtual int underflow();
virtual streambuf *setbuf( char *, int );
virtual streampos seekoff( streamoff,
               ios::seekdir,
               ios::openmode );
virtual int sync();

filebuf::attach()

attach a filebuf object to an open file

Synopsis:

#include <fstream.h>
public:
filebuf *filebuf::attach( filedesc hdl );

Semantics:

The attach() public member function connects an existing filebuf object to an open file via the file's descriptor or handle specified by hdl. If the filebuf object is already connected to a file, this function fails. Otherwise, the attach() public member function extracts information from the file system to determine the capabilities of the file, and hence the filebuf object.

Results:

The attach() public member function returns a pointer to the filebuf object on success, otherwise it returns NULL.

filebuf::close()

disconnect the filebuf object from a file

Synopsis:

#include <fstream.h>
public:
filebuf *filebuf::close();

Semantics:

The close() public member function disconnects the filebuf object from a connected file, and closes the file. Any buffered output is flushed before the file is closed.

Results:

The close() public member function returns a pointer to the filebuf object on success, otherwise NULL is returned.

filebuf::fd()

get the file descriptor connected to the filebuf object

Synopsis:

#include <fstream.h>
public:
filedesc filebuf::fd() const;

Semantics:

The fd() public member function queries the state of the filebuf object file handle.

Results:

The fd() public member function returns the file descriptor or handle of the file to which the filebuf object is currently connected. If the filebuf object isn't currently connected to a file, EOF is returned.

filebuf::filebuf()

create a filebuf object

Synopsis:

#include <fstream.h>
public:
filebuf::filebuf();
filebuf::filebuf( filedesc hdl );
filebuf::filebuf( filedesc hdl, char *buf, 
                  int len );

Semantics:

There are three forms of the public filebuf constructor:

The first creates a filebuf object that isn't currently connected to any file. A call to the fd() member function for this created filebuf object returns EOF, unless a file is connected using the attach() member function.
The second form creates a filebuf object that's connected to an open file. The file is specified via the hdl parameter, which is a file descriptor or handle.
This form of the public filebuf constructor is similar to using the default constructor, and calling the attach() member function. A call to the fd() member function for this created filebuf object returns hdl.
The third form creates a filebuf object that's connected to an open file and that uses the buffer specified by buf and len. The file is specified via the hdl parameter, which is a file descriptor or handle. If buf is NULL and/or len is less than or equal to zero, the filebuf object is unbuffered, so that reading and/or writing take place one character at a time.
This form of the public filebuf constructor is similar to using the default constructor, and calling the attach() and setbuf() member functions.

Results:

The public filebuf constructor creates a filebuf object.

filebuf::~filebuf()

destroy a filebuf object

Synopsis:

#include <fstream.h>
public:
filebuf::~filebuf();

Semantics:

The public filebuf destructor closes the file if it was explicitly opened using the open() member function. Otherwise, the destructor takes no explicit action. The streambuf destructor is called to destroy that portion of the filebuf object.

The call to the public filebuf destructor is inserted implicitly by the compiler at the point where the filebuf object goes out of scope.

Results:

The filebuf object is destroyed.

filebuf::is_open()

query the filebuf object's state

Synopsis:

#include <fstream.h>
public:
int filebuf::is_open();

Semantics:

The is_open() public member function queries the filebuf object state.

Results:

The is_open() public member function returns a non-zero value if the filebuf object is currently connected to a file. Otherwise, it returns zero.

filebuf::open()

connect the filebuf object to a file, and open it

Synopsis:

#include <fstream.h>
public:
filebuf *filebuf::open( const char *name,
               ios::openmode mode,
               int prot = filebuf::openprot );

Semantics:

The open() public member function is used to connect the filebuf object to a file specified by the name parameter. The file is opened using the specified mode. For details about the mode parameter, see the description of ios::openmode. The prot parameter specifies the file protection attributes to use when creating a file.

Results:

The open() public member function returns a pointer to the filebuf object on success, otherwise NULL is returned.

filebuf::openprot

default file protection

Synopsis:

#include <fstream.h>
public:
static int const filebuf::openprot;

Semantics:

The openprot public member data is used to specify the default file protection to be used when creating new files. This value is used as the default if no user-specified value is provided.

The default value is octal 0644. This is generally interpreted as follows:

Owner: read/write
Group: read
World: read

Note that not all operating systems support all bits.

filebuf::overflow()

write data from the put area in the file

Synopsis:

#include <fstream.h>
public:
virtual int filebuf::overflow( int ch = EOF );

Semantics:

The overflow() public virtual member function provides the output communication to the file to which the filebuf object is connected. Member functions in the streambuf class call the overflow() public virtual member function for the derived class when the put area is full.

The overflow() public virtual member function performs the following steps:

If no buffer is present, a buffer is allocated with the streambuf::allocate() member function, which may call the doallocate() virtual member function. The put area is then set up. If, after calling streambuf::allocate(), no buffer is present, the filebuf object is unbuffered and ch (if not EOF) is written directly to the file without buffering, and no further action is taken.
If the get area is present, it's flushed with a call to the sync() virtual member function. Note that the get area won't be present if a buffer was set up in step 1.
If ch isn't EOF, it's added to the put area, if possible.
Any characters in the put area are written to the file.
The put area pointers are updated to reflect the new state of the put area. If the write didn't complete, the unwritten portion of the put area is still present. If the put area was full before the write, ch (if not EOF) is placed at the start of the put area. Otherwise, the put area is empty.

Results:

The overflow() public virtual member function returns __NOT_EOF on success, otherwise EOF is returned.

filebuf::pbackfail()

handle a failed attempt to put back a character

Synopsis:

#include <fstream.h>
public:
virtual int filebuf::pbackfail( int ch );

Semantics:

The pbackfail() public virtual member function handles an attempt to put back a character when there's no room at the beginning of the get area. The pbackfail() public virtual member function first calls the sync() virtual member function to flush the put area, and then it attempts to seek backwards over ch in the associated file.

Results:

The pbackfail() public virtual member function returns ch on success, otherwise EOF is returned.

filebuf::seekoff()

position the filebuf at a given offset

Synopsis:

#include <fstream.h>
public:
virtual streampos filebuf::seekoff( 
                      streamoff offset,
                      ios::seekdir dir,
                      ios::openmode mode );

Semantics:

The seekoff() public virtual member function is used to position the filebuf object (and hence the file) at a particular offset, so that subsequent input or output operations commence from that point. The offset is specified by the offset and dir parameters.

Since the get area and put area pointers are tied together for the filebuf object, the mode parameter is ignored.

Before the actual seek occurs, the get area and put area of the filebuf object are flushed via the sync() virtual member function. Then, the new position in the file is calculated and the seek takes place.

The dir parameter may be ios::beg, ios::cur, or ios::end, and is interpreted in conjunction with the offset parameter as follows:

ios::beg: the offset is relative to the start, and should be a positive value
ios::cur: the offset is relative to the current position, and may be positive (seek towards end) or negative (seek towards start)
ios::end: the offset is relative to the end, and should be a negative value

If the dir parameter has any other value, or the offset parameter doesn't have an appropriate sign, the seekoff() public virtual member function fails.

Results:

The seekoff() public virtual member function returns the new position in the file on success, otherwise EOF is returned.

filebuf::setbuf()

offer a buffer to the filebuf object

Synopsis:

#include <fstream.h>
public:
virtual streambuf *filebuf::setbuf( char *buf, 
                                    int len );

Semantics:

The setbuf() public virtual member function is used to offer a buffer, specified by buf and len to the filebuf object. If the buf parameter is NULL or the len is less than or equal to zero, the request is to make the filebuf object unbuffered.

If the filebuf object is already connected to a file and has a buffer, the offer is rejected. In other words, a call to the setbuf() public virtual member function after the filebuf object has started to be used usually fails because the filebuf object has set up a buffer.

If the request is to make the filebuf object unbuffered, the offer succeeds.

If the buf is too small (less than five characters), the offer is rejected. Five characters are required to support the default putback area.

Otherwise, the buf is acceptable and the offer succeeds.

If the offer succeeds, the streambuf::setb() member function is called to set up the pointers to the buffer. The streambuf::setb() member function releases the old buffer (if present), depending on how that buffer was allocated.

Calls to the setbuf() public virtual member function are usually made by a class derived from the fstream class, not directly by a user program.

Results:

The setbuf() public virtual member function returns a pointer to the filebuf object on success, otherwise it returns NULL.

filebuf::sync()

synchronize the filebuf object with the external file or device

Synopsis:

#include <fstream.h>
public:
virtual int filebuf::sync();

Semantics:

The sync() public virtual member function synchronizes the filebuf object with the external file or device. If the put area contains characters it's flushed. This leaves the file positioned after the last written character. If the get area contains buffered (unread) characters, the file is backed up to be positioned after the last read character.

The get area and put area never both contain characters.

Results:

The sync() public virtual member function returns __NOT_EOF on success, otherwise it returns EOF.

filebuf::underflow()

provide input communication from the file

Synopsis:

#include <fstream.h>
public:
virtual int filebuf::underflow();

Semantics:

The underflow() public virtual member function provides the input communication from the file to which the filebuf object is connected. Member functions in the streambuf class call the underflow() public virtual member function for the derived class when the get area is empty.

The underflow() public virtual member function performs the following steps:

If no reserve area is present, a buffer is allocated with the streambuf::allocate() member function, which might call the doallocate() virtual member function. If, after calling allocate(), no reserve area is present, the filebuf object is unbuffered, and a one-character reserve area (plus putback area) is set up to do unbuffered input. This buffer is embedded in the filebuf object. The get area is set up as empty.
If the put area is present, it's flushed using the sync() virtual member function.
The unused part of the get area is used to read characters from the file connected to the filebuf object. The get area pointers are then set up to reflect the new get area.

Results:

The underflow() public virtual member function returns the first unread character of the get area, on success, otherwise it returns EOF. Note that the get pointer isn't advanced on success.

`fstream` Class

Declared:

fstream.h

Derived from:

fstreambase, iostream

The fstream class is used to access files for reading and writing. The file can be opened and closed, and read, write and seek operations can be performed.

The fstream class provides very little of its own functionality. It's derived from both the fstreambase and iostream classes. The fstream constructors, destructor and member function provide simplified access to the appropriate equivalents in the base classes.

Of the available I/O stream classes, creating an fstream object is the preferred method of accessing a file for both input and output.

Public Member Functions

The following public member functions are declared:

fstream();
fstream( char const *,
         ios::openmode = ios::in|ios::out,
         int = filebuf::openprot );
fstream( filedesc );
fstream( filedesc, char *, int );
~fstream();
void open( char const *,
           ios::openmode = ios::in|ios::out,
           int = filebuf::openprot );

fstream::fstream()

create a fstream object

Synopsis:

#include <fstream.h>
public:
fstream::fstream();
fstream::fstream( 
    const char *name,
    ios::openmode mode = ios::in|ios::out,
    int prot = filebuf::openprot );
fstream::fstream( filedesc hdl );
fstream::fstream( filedesc hdl, char *buf, 
                  int len );

Semantics:

There are four forms of the public fstream constructor:

The first creates an fstream object that isn't connected to a file. The open() or attach() member functions should be used to connect the fstream object to a file.
The second form creates an fstream object that's connected to the file specified by the name parameter, using the specified mode and prot parameters. The connection is made via the C library open() function.
If the open() fails, ios::failbit and ios::badbit are set in the error state in the inherited ios object.
The third form creates an fstream object that's attached to the file specified by the hdl parameter. If the attachment fails, ios::failbit and ios::badbit are set in the error state in the inherited ios object.
The fourth form creates an fstream object that's connected to the file specified by the hdl parameter. The buffer specified by the buf and len parameters is offered to the associated filebuf object via the setbuf() member function. If the buf parameter is NULL or the len is less than or equal to zero, the filebuf is unbuffered, so that each read or write operation reads or writes a single character at a time.
If the connection to hdl fails, ios::failbit and ios::badbit are set in the error state in the inherited ios object. If the setbuf() fails, ios::failbit is set in the error state in the inherited ios object.

Results:

The public fstream constructor creates an fstream object.

fstream::~fstream()

destroy a fstream object

Synopsis:

#include <fstream.h>
public:
fstream::~fstream();

Semantics:

The public fstream destructor doesn't do anything explicit. The call to this destructor is inserted implicitly by the compiler at the point where the fstream object goes out of scope.

Results:

The fstream object is destroyed.

fstream::open()

connect the fstream object to a file

Synopsis:

#include <fstream.h>
public:
void fstream::open( 
        const char *name,
        ios::openmode mode = ios::in|ios::out,
        int prot = filebuf::openprot );

Semantics:

The open() public member function connects the fstream object to the file specified by the name parameter, using the specified mode and prot parameters. The mode parameter is optional, and usually isn't specified unless additional bits (such as ios::binary or ios::text) are to be specified. The connection is made via the C library open() function.

Results:

If the open fails, ios::failbit is set in the error state in the inherited ios object.

`fstreambase` Class

Declared:

fstream.h

Derived from:

ios

Derived by:

ifstream, ofstream, fstream

The fstreambase class is a base class that provides common functionality for the three file-based classes, ifstream, ofstream and fstream. The fstreambase class is derived from the ios class, providing the stream state information, plus it provides member functions for opening and closing files. The actual file manipulation work is performed by the filebuf class.

It isn't intended that fstreambase objects be created. Instead, you should create an ifstream, ofstream or fstream object.

Protected Member Functions

The following member functions are declared in the protected interface:

fstreambase();
fstreambase( char const *,
             ios::openmode,
             int = filebuf::openprot );
fstreambase( filedesc );
fstreambase( filedesc, char *, int );
~fstreambase();

Public Member Functions

The following member functions are declared in the public interface:

void attach( filedesc );
void close();
filedesc fd() const;
int is_open() const;
void open( char const *,
        ios::openmode,
        int = filebuf::openprot );
filebuf *rdbuf() const;
void setbuf( char *, int );

fstreambase::attach()

attach the fstreambase object to a file

Synopsis:

#include <fstream.h>
public:
void fstreambase::attach( filedesc hdl );

Semantics:

The attach() public member function connects the fstreambase object to the file specified by the hdl parameter.

Results:

If the attach() public member function fails, ios::failbit bit is set in the error state in the inherited ios object. The error state in the inherited ios object is cleared on success.

fstreambase::close()

disconnect the fstreambase object from its file

Synopsis:

#include <fstream.h>
public:
void fstreambase::close();

Semantics:

The close() public member function disconnects the fstreambase object from the file with which it's associated. If the fstreambase object isn't associated with a file, the close() public member function fails.

Results:

If the close() public member function fails, ios::failbit is set in the error state in the inherited ios object.

fstreambase::fstreambase()

create a fstreambase object

Synopsis:

#include <fstream.h>
protected:
fstreambase::fstreambase();
fstreambase::fstreambase( char const *name,
                ios::openmode mode,
                int prot = filebuf::openprot );
fstreambase::fstreambase( filedesc hdl );
fstreambase::fstreambase( filedesc hdl,
                          char *buf,
                          int len );

Semantics:

There are four forms of the protected fstreambase constructor:

The first form creates an fstreambase object that's initialized, but not connected to anything. The open() or attach() member function should be used to connect the fstreambase object to a file.
The second form creates an fstreambase object that's initialized and connected to the file indicated by name using the specified mode and prot. The fstreambase object is connected to the specified file via the open() C library function.
If the call to open() for the file fails, ios::failbit and ios::badbit are set in the error state in the inherited ios object.
The third form creates an fstreambase object that's initialized and connected to the open file specified by the hdl parameter. If the attachment to the file fails, ios::failbit and ios::badbit are set in the error state in the inherited ios object.
The forth form creates an fstreambase object that's initialized and connected to the open file specified by the hdl parameter. The buffer, specified by the buf and len parameters, is offered via the setbuf() virtual member function to be used as the reserve area for the filebuf associated with the fstreambase object.
If the attachment to the file fails, ios::failbit and ios::badbit are set in the error state in the inherited ios object.

Results:

The protected fstreambase constructor produces an fstreambase object.

fstreambase::~fstreambase()

destroy a fstreambase object

Synopsis:

#include <fstream.h>
protected:
fstreambase::~fstreambase();

Semantics:

The protected fstreambase destructor doesn't do anything explicit. The filebuf object associated with the fstreambase object is embedded within the fstreambase object, so the filebuf destructor is called. The ios destructor is called for that portion of the fstreambase object.

The call to the protected fstreambase destructor is inserted implicitly by the compiler at the point where the fstreambase object goes out of scope.

Results:

The fstreambase object is destroyed.

fstreambase::is_open()

query the state of the associated file

Synopsis:

#include <fstream.h>
public:
int fstreambase::is_open() const;

Semantics:

The is_open() public member function queries the current state of the file associated with the fstreambase object. Calling the is_open() public member function is equivalent to calling the fd() member function and testing for EOF.

Results:

The is_open() public member function returns a non-zero value if the fstreambase object is currently connected to a file, otherwise it returns zero.

fstreambase::fd()

get the descriptor of the attached file

Synopsis:

#include <fstream.h>
public:
filedesc fstreambase::fd() const;

Semantics:

The fd() public member function returns the file descriptor for the file to which the fstreambase object is connected.

Results:

The fd() public member function returns the file descriptor for the file to which the fstreambase object is connected. If the fstreambase object isn't currently connected to a file, EOF is returned.

fstreambase::open()

connect the fstreambase object to a file, and open it

Synopsis:

#include <fstream.h>
public:
void fstreambase::open( const char *name,
               ios::openmode mode,
               int prot = filebuf::openprot );

Semantics:

The open() public member function connects the fstreambase object to the file specified by name, using the specified mode and prot. The connection is made via the C library open() function.

Results:

If the open() fails, ios::failbit is set in the error state in the inherited ios object. The error state in the inherited ios object is cleared on success.

fstreambase::rdbuf()

return the address of the filebuf object

Synopsis:

#include <fstream.h>
public:
filebuf *fstreambase::rdbuf() const;

Semantics:

The rdbuf() public member function returns the address of the filebuf object currently associated with the fstreambase object.

Results:

The rdbuf() public member function returns a pointer to the filebuf object currently associated with the fstreambase object. If there's no associated filebuf, NULL is returned.

fstreambase::setbuf()

offer the specfied buffer to the filebuf object

Synopsis:

#include <fstream.h>
public:
void fstreambase::setbuf( char *buf, int len );

Semantics:

The setbuf() public member function offers the specified buffer to the filebuf object associated with the fstreambase object. The filebuf might or might not reject the offer, depending on its state.

Results:

If the offer is rejected, ios::failbit is set in the error state in the inherited ios object.

`ifstream` Class

Declared:

fstream.h

Derived from:

fstreambase, istream

The ifstream class is used to access existing files for reading. Such files can be opened and closed, and read and seek operations can be performed.

The ifstream class provides very little of its own functionality. Derived from both the fstreambase and istream classes, its constructors, destructor and member functions provide simplified access to the appropriate equivalents in those base classes.

Of the available I/O stream classes, creating an ifstream object is the preferred method of accessing a file for input-only operations.

Public Member Functions

The following public member functions are declared:

ifstream();
ifstream( char const *,
          ios::openmode = ios::in,
          int = filebuf::openprot );
ifstream( filedesc );
ifstream( filedesc, char *, int );
~ifstream();
void open( char const *,
           ios::openmode = ios::in,
           int = filebuf::openprot );

ifstream::ifstream()

create a ifstream object

Synopsis:

#include <fstream.h>
public:
ifstream::ifstream();
ifstream::ifstream( const char *name,
              ios::openmode mode = ios::in,
              int prot = filebuf::openprot );
ifstream::ifstream( filedesc hdl );
ifstream::ifstream( filedesc hdl, 
                    char *buf,
                    int len );

Semantics:

There are four forms of the public ifstream constructor:

The first creates an ifstream object that isn't connected to a file. The open() or attach() member functions should be used to connect the ifstream object to a file.
The second form creates an ifstream object that's connected to the file specified by the name parameter, using the specified mode and prot parameters. The connection is made via the C library open() function.
If the open() fails, ios::failbit and ios::badbit are set in the error state in the inherited ios object.
The third form creates an ifstream object that's attached to the file specified by the hdl parameter.
If the attachment fails, ios::failbit and ios::badbit are set in the error state in the inherited ios object.
The fourth form creates an ifstream object that's connected to the file specified by the hdl parameter. The buffer specified by the buf and len parameters is offered to the associated filebuf object via the setbuf() member function. If the buf parameter is NULL, or the len is less than or equal to zero, the filebuf is unbuffered, so that each read or write operation reads or writes a single character at a time.
If the connection to hdl fails, ios::failbit and ios::badbit are set in the error state in the inherited ios object. If the call to setbuf() fails, ios::failbit is set in the error state in the inherited ios object.

Results:

The public ifstream constructor produces an ifstream object.

ifstream::~ifstream()

destroy a ifstream object

Synopsis:

#include <fstream.h>
public:
ifstream::~ifstream();

Semantics:

The public ifstream destructor doesn't do anything explicit. The call to the public ifstream destructor is inserted implicitly by the compiler at the point where the ifstream object goes out of scope.

Results:

The ifstream object is destroyed.

ifstream::open()

connect the ifstream object to a file

Synopsis:

#include <fstream.h>
public:
void ifstream::open( const char *name,
            ios::openmode mode = ios::in,
            int prot = filebuf::openprot );

Semantics:

The open() public member function connects the ifstream object to the file specified by the name parameter, using the specified mode and prot parameters. The mode parameter is optional, and usually isn't specified unless additional bits (such as ios::binary or ios::text) are to be specified. The connection is made via the C library open() function.

Results:

If the open fails, ios::failbit is set in the error state in the inherited ios object.

`ios` Class

Declared:

iostream.h

Derived from:

istream, ostream

The ios class is used to group together common functionality needed for other derived stream classes. It isn't intended that objects of type ios be created.

This class maintains state information about the stream. (the ios name can be thought of as a short-form for I/O State). Error flags, formatting flags, and values and the connection to the buffers used for the input and output are all maintained by the ios class. No information about the buffer itself is stored in an ios object, merely the pointer to the buffer information.

Protected Member Functions

The following member functions are declared in the protected interface:

ios();
void init( streambuf * );
void setstate( ios::iostate );

Public Enumerations

The following enumeration typedefs are declared in the public interface:

typedef int  iostate;
typedef long fmtflags;
typedef int  openmode;
typedef int  seekdir;

Public Member Functions

The following member functions are declared in the public interface:

ios( streambuf * );
virtual ~ios();

ostream *tie() const;
ostream *tie( ostream * );
streambuf *rdbuf() const;
ios::iostate rdstate() const;
ios::iostate clear( ios::iostate = 0 );
int good() const;
int bad() const;
int eof() const;
int fail() const;
ios::iostate exceptions( ios::iostate );
ios::iostate exceptions() const;
ios::fmtflags setf( ios::fmtflags, ios::fmtflags );
ios::fmtflags setf( ios::fmtflags );
ios::fmtflags unsetf( ios::fmtflags );
ios::fmtflags flags( ios::fmtflags );
ios::fmtflags flags() const;
char fill( char );
char fill() const;
int precision( int );
int precision() const;
int width( int );
int width() const;
long &iword( int );
void *&pword( int );
static void sync_with_stdio();
static ios::fmtflags bitalloc();
static int xalloc();

Public Member Operators

The following member operators are declared in the public interface:

operator void *() const;
int operator !() const;

ios::bad()

query the state of the ios object's badbit flag

Synopsis:

#include <iostream.h>
public:
int ios::bad() const;

Semantics:

The bad() public member function queries the state of the ios object.

Results:

The bad() public member function returns a non-zero value if ios::badbit is set in the error state in the inherited ios object, otherwise zero is returned.

ios::bitalloc()

allocate a new fmtflag bit

Synopsis:

#include <iostream.h>
public:
static ios::fmtflags ios::bitalloc();

Semantics:

The bitalloc() public static member function is used to allocate a new ios::fmtflags bit for use by user-derived classes.

Because the bitalloc() public static member function manipulates static member data, its behavior isn't tied to any one object but affects the entire class of objects. The value that's returned by the bitalloc() public static member function is valid for all objects of all classes derived from the ios class. No subsequent call to the bitalloc() public static member function will return the same value as a previous call.

The bit value allocated may be used with the member functions that query and affect ios::fmtflags. In particular, the bit can be set with the setf() or flags() member functions, or the setiosflags() manipulator, and reset with the unsetf() or flags() member functions or the resetiosflags() manipulator.

There are two constants defined in iostream.h that indicate the number of bits available when a program starts:

_LAST_FORMAT_FLAG: indicates the last bit used by the built-in format flags described by ios::fmtflags.
_LAST_FLAG_BIT: indicates the last bit that's available for the bitalloc() public static member function to allocate.

The difference between the bit positions indicates how many bits are available.

Results:

The bitalloc() public static member function returns the next available ios::fmtflags bit for use by user-derived classes. If no more bits are available, zero is returned.

ios::clear()

clear the iostate for the object

Synopsis:

#include <iostream.h>
public:
iostate ios::clear( ios::iostate flags = 0 );

Semantics:

The clear() public member function is used to change the current value of ios::iostate in the ios object. ios::iostate is cleared, all bits specified in flags are set.

Results:

The clear() public member function returns the previous value of ios::iostate.

ios::eof()

query the state of the ios object's end-of-file bit

Synopsis:

#include <iostream.h>
public:
int ios::eof() const;

Semantics:

The eof() public member function queries the state of the ios object.

Results:

The eof() public member function returns a non-zero value if ios::eofbit is set in the error state in the inherited ios object, otherwise zero is returned.

ios::exceptions()

query and/or set the bits that enable exceptions

Synopsis:

#include <iostream.h>
public:
ios::iostate ios::exceptions() const;
ios::iostate ios::exceptions( int enable );

Semantics:

The exceptions() public member function queries and/or sets the bits that control which exceptions are enabled. ios::iostate within the ios object is used to enable and disable exceptions.

When a condition arises that sets a bit in ios::iostate, a check is made to see if the same bit is also set in the exception bits. If so, an exception is thrown. Otherwise, no exception is thrown.

The first form of the exceptions() public member function looks up the current setting of the exception bits. The bit values are those described by ios::iostate.

The second form of the function sets the exceptions bits to those specified in the enable parameter, and returns the current settings.

Results:

The exceptions() public member function returns the previous setting of the exception bits.

ios::fail()

query the state of the ios object's badbit and failbit flags

Synopsis:

#include <iostream.h>
public:
int ios::fail() const;

Semantics:

The fail() public member function queries the state of the ios object.

Results:

The fail() public member function returns a non-zero value if ios::failbit or ios::badbit is set in the error state in the inherited ios object, otherwise zero is returned.

ios::fill()

query and/or set the fill character

Synopsis:

#include <iostream.h>
public:
char ios::fill() const;
char ios::fill( char fillchar );

Semantics:

The fill() public member function queries and/or sets the fill character used when the size of a formatted object is smaller than the format width specified.

The first form of the fill() public member function looks up the current value of the fill character.

The second form of the function sets the fill character to fillchar.

By default, the fill character is a space.

Results:

The fill() public member function returns the previous value of the fill character.

ios::flags()

query and/or set the format flags

Synopsis:

#include <iostream.h>
public:
ios::fmtflags ios::flags() const;
ios::fmtflags ios::flags( ios::fmtflags setbits );

Semantics:

The flags() public member function is used to query and/or set the value of ios::fmtflags in the ios object.

The first form of the flags() public member function looks up the current ios::fmtflags value.

The second form of the function sets ios::fmtflags to the value specified in the setbits parameter.

The setf() public member function only turns bits on, while the flags() public member function turns some bits on and some bits off.

Results:

The flags() public member function returns the previous ios::fmtflags value.

ios::fmtflags

a set of bits for specifying I/O formats

Synopsis:

#include <iostream.h>
public:
enum fmt_flags {
  skipws     = 0x0001, // skip whitespace
  left       = 0x0002, // align field to left edge
  right      = 0x0004, // align field to right edge
  internal   = 0x0008, // sign at left, value at 
                       // right
  dec        = 0x0010, // decimal conversion for 
                       // integers
  oct        = 0x0020, // octal conversion for 
                       // integers
  hex        = 0x0040, // hexadecimal conversion 
                       // for integers
  showbase   = 0x0080, // show dec/octal/hex base 
                       // on output
  showpoint  = 0x0100, // show decimal and digits 
                       // on output
  uppercase  = 0x0200, // use uppercase for format 
                       // characters
  showpos    = 0x0400, // use + for output positive 
                       // numbers
  scientific = 0x0800, // use scientific notation 
                       // for output
  fixed      = 0x1000, // use floating notation for 
                       // output
  unitbuf    = 0x2000, // flush stream after output
  stdio      = 0x4000, // flush stdout/stderr after 
                       // output

  basefield  = dec | oct | hex,
  adjustfield= left | right | internal,
  floatfield = scientific | fixed
};
typedef long fmtflags;

Semantics:

The type ios::fmt_flags is a set of bits representing methods of:

formatting objects written to the stream
interpreting objects read from the stream.

The type fmtflags represents the same set of bits, but uses a long to represent the values, thereby avoiding problems made possible by the compiler's ability to use smaller types for enumerations.

You should use the type ios::fmtflags.

The bit values defined by the type fmtflags are set and read by the member functions setf(), unsetf() and flags(), as well as the manipulators setiosflags() and resetiosflags().

Because one field is used to store all of these bits, there are three special values used to mask various groups of bits. These values are named ios::basefield, ios::adjustfield and ios::floatfield, and are discussed with the bits that they're used to mask.

ios::skipws controls whether or not whitespace characters are automatically skipped when using an operator >>() extractor. If ios::skipws is on, any use of the operator >>() extractor skips whitespace characters before inputting the next item. Otherwise, skipping of whitespace characters must be handled by the program.

ios::left, ios::right and ios::internal control the alignment of items written using an operator <<() inserter. These bits are usually used in conjunction with the format width and fill character.

ios::adjustfield can be used to mask the alignment bits returned by the setf(), unsetf() and flags() member functions, and for setting new values to ensure that no other bits are accidentally affected.

When the item to be written is smaller than the format width specified, fill characters are written to occupy the additional space:

If ios::left is in effect, the item is written in the left portion of the available space, and fill characters are written in the right portion.
If ios::right is in effect, the item is written in the right portion of the available space, and fill characters are written in the left portion.
If ios::internal is in effect, any sign character or base indicator is written in the left portion, the digits are written in the right portion, and fill characters are written in between.

If no alignment is specified, ios::right is assumed.

If the item to be written is as big as or bigger than the format width specified, no fill characters are written, and the alignment is ignored.

ios::dec, ios::oct and ios::hex control the base used to format integers being written to the stream, and also control the interpretation of integers being read from the stream.

ios::basefield can be used to mask the base bits returned by the member functions setf(), unsetf() and flags(), and for setting new values to ensure that no other bits are accidentally affected.

When an integer is being read from the stream, these bits control the base used for the interpretation of the digits. If none of these bits is set, the number is interpreted, based on the starting character(s), as given in the following table:

Starting character(s)	Interpretation
`0x` or `0X`	hexadecimal (digits `0123456789`, plus the letters `abcdef` or `ABCDEF`)
`0` (zero)	octal (digits `01234567`)
other	decimal (digits `0123456789`)

If one of the bits is set, then the prefix isn't necessary, and the number is interpreted according to the bit.

When any one of the integer types is being written to the stream, it can be written in decimal, octal or hexadecimal. If none of these bits is set, ios::dec is assumed.

If ios::dec is set (or assumed), the integer is written in decimal (digits 0123456789). No prefix is included.

If ios::oct is set, the integer is written in octal (digits 01234567). No sign character is written, as the number is treated as an unsigned quantity on conversion to octal.

If ios::hex is set, the integer is written in hexadecimal (digits 0123456789, plus the letters abcdef or ABCDEF, depending on the setting of ios::uppercase). No sign character is written, as the number is treated as an unsigned quantity on conversion to hexadecimal.

ios::showbase controls whether or not integers written to the stream in octal or hexadecimal form have a prefix that indicates the base of the number. If the bit is set, decimal numbers are written without a prefix, octal numbers are written with the prefix 0 (zero), and hexadecimal numbers are written with the prefix 0x or 0X, depending on the setting of ios::uppercase. If the ios::showbase isn't set, no prefixes are written.

ios::showpoint is used to control whether or not the decimal point and trailing zeroes are trimmed when floating-point numbers are written to the stream. If the bit is set, no trimming is done, causing the number to appear with the specified format precision. If the bit isn't set, any trailing zeroes after the decimal point are trimmed, and if not followed by any digits, the decimal point is removed as well.

ios::uppercase is used to force to upper-case all letters used in formatting numbers, including the letter-digits abcdef, the x hexadecimal prefix, and the e used for the exponents in floating-point numbers.

ios::showpos controls whether or not a + is added to the front of positive integers being written to the stream. If the bit is set, the number is positive and the number is being written in decimal, a + is written before the first digit.

ios::scientific and ios::fixed control the form used for writing floating-point numbers to the stream. Floating-point numbers can be written in scientific notation (also called exponential notation) or in fixed-point notation.

ios::floatfield can be used to mask the floating-format bits returned by the member functions setf(), unsetf() and flags(), and for setting new values to ensure that no other bits are accidentally affected.

If ios::scientific is set, the floating-point number is written with a leading - sign (for negative numbers), a digit, a decimal point, more digits, an e (or E if ios::uppercase is set), a + or - sign, and two or three digits representing the exponent. The digit before the decimal isn't zero unless the number is zero. The total number of digits before and after the decimal is equal to the specified format precision. If ios::showpoint isn't set, trimming of the decimal and digits following the decimal might occur.

If ios::fixed is set, the floating-point number is written with a - sign (for negative numbers), at least one digit, the decimal point, and as many digits following the decimal as specified by the format precision. If ios::showpoint isn't set, trimming of the decimal and digits following the decimal might occur.

If neither ios::scientific nor ios::fixed is specified, the floating-point number is formatted using scientific notation provided at least one of the following conditions is met:

the exponent is less than -4, or,
the exponent is greater than the format precision.

Otherwise, fixed-point notation is used.

ios::unitbuf controls whether or not the stream is flushed after each item is written. If the bit is set, every item that's written to the stream is followed by a flush operation, which ensures that the I/O stream buffer associated with the stream is kept empty, immediately transferring the data to its final destination.

ios::stdio controls whether or not the stream is synchronized after each item is written. If the bit is set, every item that's written to the stream causes the stream to be synchronized, which means any input or output buffers are flushed so that an I/O operation performed using C (not C++) I/O behaves in an understandable way. If the output buffer isn't flushed, writing using C++ and then C I/O functions could cause the output from the C functions to appear before the output from the C++ functions, since the characters might be sitting in the C++ output buffer. Similarly, after the C output operations are done, a call should be made to the C library fflush() function on the appropriate stream before resuming C++ output operations.

ios::good()

check the state of the ios object

Synopsis:

#include <iostream.h>
public:
int ios::good() const;

Semantics:

The good() public member function queries the state of the ios object.

Results:

The good() public member function returns a non-zero value if none of ios::iostate is clear, otherwise zero is returned.

ios::init()

initialize the ios object

Synopsis:

#include <iostream.h>
protected:
void ios::init( streambuf *sb );

Semantics:

The init() public protected member function is used by derived classes to explicitly initialize the ios portion of the derived object, and to associate a streambuf with the ios object. The init() public protected member function performs the following steps:

The default fill character is set to a space.
The format precision is set to six.
The streambuf pointer (returned by the rdbuf() member function) is set to sb.
The remaining fields of the ios are initialized to zero.

Results:

If sb is NULL, the ios::badbit is set in the error state in the inherited ios object.

ios::ios()

create a ios object

Synopsis:

#include <iostream.h>
protected:
ios::ios();

public:
ios::ios( streambuf *sb );

Semantics:

There are two forms of the ios constructor:

The first form is a protected member function. It creates a default ios object that's initialized, but doesn't have an associated streambuf. Initialization of an ios object is handled by the init() protected member function.
The second form is a public member function. It creates an ios object that's initialized and has an associated streambuf. Initialization of an ios object is handled by the init() protected member function. Once this is completed, the ios object's streambuf pointer is set to sb. If sb isn't NULL, ios::badbit is cleared from the error state in the inherited ios object.

Results:

The protected ios constructor creates an ios object, and sets ios::badbit in the error state in the inherited ios object.
The public ios constructor creates an ios object and, if sb is NULL, sets ios::badbit in the error state in the inherited ios object.

ios::~ios()

destroy a ios object

Synopsis:

#include <iostream.h>
public:
virtual ios::~ios();

Semantics:

The public virtual ios destructor destroys an ios object. The call to it is inserted implicitly by the compiler at the point where the ios object goes out of scope.

Results:

The ios object is destroyed.

ios::iostate

a set of bits that reflects the state of the ios object

Synopsis:

#include <iostream.h>
public:
enum io_state {
    goodbit = 0x00, // no errors
    badbit  = 0x01, // operation failed, 
                    // may not proceed
    failbit = 0x02, // operation failed, 
                    // may proceed
    eofbit  = 0x04  // end of file encountered
};
typedef int iostate;

Semantics:

The type ios::io_state is a set of bits representing the current state of the stream. The type iostate represents the same set of bits, but uses an int to represent the values, thereby avoiding problems made possible by the compiler's ability to use smaller types for enumerations.

Use the ios::iostate, not ios::io_state.

The bit values defined by the type iostate can be read and set by the member functions rdstate() and clear(), and can be used to control exception handling with the member function exceptions().

ios::badbit represents the state where the stream is no longer usable because of some error condition.

ios::failbit represents the state where the previous operation on the stream failed, but the stream is still usable. Subsequent operations on the stream are possible, but the state must be cleared using the clear() member function.

ios::eofbit represents the state where the end-of-file condition has been encountered. The stream may still be used, but the state must be cleared using the clear() member function.

Even though ios::goodbit isn't a bit value (because its value is zero, which has no bits on), it's provided for completeness.

ios::iword()

return a reference to a long integer

Synopsis:

#include <iostream.h>
public:
long &ios::iword( int index );

Semantics:

The iword() public member function creates a reference to a long int, which may be used to store and retrieve any suitable integer value. The index parameter specifies which long int is to be referenced, and must be obtained from a call to the xalloc() static member function.

The iword() and pword() public member functions return references to the same storage with a different type. Therefore, each index obtained from the xalloc() static member function can be used only for an integer or a pointer, not both.

Since the iword() public member function returns a reference and the ios class can't predict how many such items will be required by a program, it should be assumed that each call to the xalloc() static member function invalidates all previous references returned by the iword() public member function. Therefore, the iword() public member function should be called each time the reference is needed.

Results:

The iword() public member function returns a reference to a long int.

ios::openmode

a set of bits that represents ways of opening a stream

Synopsis:

#include <iostream.h>
public:
enum open_mode {
  in        = 0x0001,  // open for input
  out       = 0x0002,  // open for output
  atend     = 0x0004,  // seek to end after opening
  append    = 0x0008,  // open for output, append
                       // to the end
  truncate  = 0x0010,  // discard contents after 
                       // opening
  nocreate  = 0x0020,  // open only an existing 
                       // file
  noreplace = 0x0040,  // open only a new file
  text      = 0x0080,  // open as text file
  binary    = 0x0100,  // open as binary file

  app       = append,  // synonym
  ate       = atend,   // synonym
  trunc     = truncate // synonym
};
typedef int openmode;

Semantics:

The type ios::open_mode is a set of bits representing ways of opening a stream. The type openmode represents the same set of bits, but uses an int to represent the values, thereby avoiding problems made possible by the compiler's ability to use smaller types for enumerations.

Use the type ios::openmode.

The bit values defined by type openmode can be specified in the constructors for stream objects, as well as in various member functions.

ios::in is specified in a stream for which input operations may be performed. ios::out is specified in a stream for which output operations may be performed.

A stream for which only ios::in is specified is referred to as an input stream.
A stream for which only ios::out is specified is referred to as an output stream.
A stream where both ios::in and ios::out are specified is referred to as an input/output stream.

ios::atend and ios::ate are equivalent, and either one is specified for streams that are to be positioned to the end before the first operation takes place. ios::ate is provided for historical purposes and compatibility with other implementations of I/O streams. Note that this bit positions the stream to the end exactly once, when the stream is opened.

ios::append and ios::app are equivalent, and either one is specified for streams that are to be positioned to the end before any and all output operations take place. ios::app is provided for historical purposes and compatibility with other implementations of I/O streams. Note that this bit causes the stream to be positioned to the end before each output operation, while ios::atend causes the stream to be positioned to the end only when first opened.

ios::truncate and ios::trunc are equivalent, and either one is specified for streams that are to be truncated to zero length before the first operation takes place. ios::trunc is provided for historical purposes and compatibility with other implementations of I/O streams.

ios::nocreate is specified if the file must exist before it's opened. If the file doesn't exist, an error occurs.

ios::noreplace is specified if the file must not exist before it's opened. That is, the file must be a new file. If the file exists, an error occurs.

ios::text is specified if the file is to be treated as a text file. A text file is divided into records, and each record is terminated by a new-line character, usually represented as \n. The new-line character is translated into a form that's compatible with the underlying file system's concept of text files. This conversion happens automatically whenever the new-line is written to the file, and the inverse conversion (to the new-line character) happens automatically whenever the end of a record is read from the file system.

ios::binary is specified if the file is to be treated as a binary file. Binary files are streams of characters. No character has a special meaning. No grouping of characters into records is apparent to the program, although the underlying file system might cause such a grouping to occur.

The following default behaviors are defined:

If ios::out is specified and none of ios::in, ios::append or ios::atend is specified, ios::truncate is assumed.
If ios::append is specified, ios::out is assumed.
If ios::truncate is specified, ios::out is assumed.
If neither ios::text nor ios::binary is specified, ios::text is assumed.

ios::operator !()

test the error state

Synopsis:

#include <iostream.h>
public:
int ios::operator !() const;

Semantics:

The operator !() public member function tests the error state in the inherited ios object of the ios object.

Results:

The operator !() public member function returns a non-zero value if either of ios::failbit or ios::badbit bits is set in the error state in the inherited ios object, otherwise zero is returned.

ios::operator void *()

convert the ios object into a pointer

Synopsis:

#include <iostream.h>
public:
ios::operator void *() const;

Semantics:

The operator void *() public member function converts the ios object into a pointer to void. The actual pointer value returned is meaningless and intended only for comparison with NULL to determine the error state in the inherited ios object of the ios object.

Results:

The operator void *() public member function returns a NULL pointer if either of ios::failbit or ios::badbit bits is set in the error state in the inherited ios object, otherwise a non-NULL pointer is returned.

ios::precision()

query and/or set the format precision

Synopsis:

#include <iostream.h>
public:
int ios::precision() const;
int ios::precision( int prec );

Semantics:

The precision() public member function is used to query and/or set the format precision. The format precision is used to control the number of digits of precision used when formatting floating-point numbers. For scientific notation, the format precision describes the total number of digits before and after the decimal point, but not including the exponent. For fixed-point notation, the format precision describes the number of digits after the decimal point.

The first form of the precision() public member function looks up the current format precision.

The second form of the function sets the format precision to prec.

By default, the format precision is six. If prec is specified to be less than zero, the format precision is set to six. Otherwise, the specified format precision is used. For scientific notation, a format precision of zero is treated as a precision of one.

Results:

The precision() public member function returns the previous format precision setting.

ios::pword()

create a reference to a pointer

Synopsis:

#include <iostream.h>
public:
void * &ios::pword( int index );

Semantics:

The pword() public member function creates a reference to a void pointer, which may be used to store and retrieve any suitable pointer value. The index parameter specifies which void pointer is to be referenced, and must be obtained from a call to the xalloc() static member function.

Since the pword() public member function returns a reference and the ios class can't predict how many such items will be required by a program, it should be assumed that each call to the xalloc() static member function invalidates all previous references returned by the pword() public member function. Therefore, the pword() public member function should be called each time the reference is needed.

Results:

The pword() public member function returns a reference to a void pointer.

ios::rdbuf()

get a pointer to the streambuf object

Synopsis:

#include <iostream.h>
public:
streambuf *ios::rdbuf() const;

Semantics:

The rdbuf() public member function looks up the pointer to the streambuf object that maintains the buffer associated with the ios object.

Results:

The rdbuf() public member function returns the pointer to the streambuf object associated with the ios object. If there's no associated streambuf object, NULL is returned.

ios::rdstate()

query the value of iostate

Synopsis:

#include <iostream.h>
public:
iostate ios::rdstate() const;

Semantics:

The rdstate() public member function is used to query the current value of ios::iostate in the ios object without modifying it.

Results:

The rdstate() public member function returns the current value of ios::iostate.

ios::seekdir

methods of seeking within a stream

Synopsis:

#include <iostream.h>
public:
enum seek_dir {
    beg, // seek from beginning
    cur, // seek from current position
    end  // seek from end
};
typedef int seekdir;

Semantics:

The type ios::seek_dir is a set of bits representing different methods of seeking within a stream. The type seekdir represents the same set of bits, but uses an int to represent the values, thereby avoiding problems made possible by the compiler's ability to use smaller types for enumerations.

Use the type ios::seekdir.

The bit values defined by type seekdir are used by the member functions seekg() and seekp(), as well the seekoff() and seekpos() member functions in classes derived from the streambuf class.

ios::beg causes the seek offset to be interpreted as an offset from the beginning of the stream. The offset is specified as a positive value.

ios::cur causes the seek offset to be interpreted as an offset from the current position of the stream. If the offset is a negative value, the seek is towards the start of the stream. Otherwise, the seek is towards the end of the stream.

ios::end causes the seek offset to be interpreted as an offset from the end of the stream. The offset is specified as a negative value.

ios::setf()

set bits in the format flags

Synopsis:

#include <iostream.h>
public:
ios::fmtflags ios::setf( ios::fmtflags onbits );
ios::fmtflags ios::setf( ios::fmtflags setbits,
                ios::fmtflags mask );

Semantics:

The setf() public member function is used to set bits in ios::fmtflags in the ios object.

The first form is used to turn on the bits that are on in the onbits parameter. (onbits is added to ios::fmtflags with an OR operation).

The second form is used to turn off the bits specified in the mask parameter and turn on the bits specified in the setbits parameter. This form is particularly useful for setting the bits described by the ios::basefield, ios::adjustfield and ios::floatfield values, where only one bit should be on at a time.

Results:

Both forms of the setf() public member function return the previous ios::fmtflags value.

ios::setstate()

set bits in the error state for the object

Synopsis:

#include <iostream.h>
protected:
void ios::setstate( int or_bits );

Semantics:

The setstate() protected member function is provided as a convenience for classes derived from the ios class. It turns on the error state in the inherited ios object bits that are set in the or_bits parameter, and leaves the other error state in the inherited ios object bits unchanged.

Results:

The setstate() protected member function sets the bits specified by or_bits in the error state in the inherited ios object.

ios::sync_with_stdio()

an obsolete function

Synopsis:

#include <iostream.h>
public:
static void ios::sync_with_stdio();

Semantics:

The sync_with_stdio() public static member function is obsolete. It's provided for compatibility.

Results:

The sync_with_stdio() public static member function has no return value.

ios::tie()

query and/or set up a connection to another stream

Synopsis:

#include <iostream.h>
public:
ostream *ios::tie() const;
ostream *ios::tie( ostream *ostrm );

Semantics:

The tie() public member function is used to query and/or set up a connection between the ios object and another stream. The connection causes the output stream specified by ostrm to be flushed whenever the ios object is about to read characters from a device or is about to write characters to an output buffer or device.

The first form of the tie() public member function is used to query the current tie.

The second form of the function is used to set the tied stream to ostrm.

Normally, the predefined streams cin and cerr set up ties to cout so that any input from the terminal flushes any buffered output, and any writes to cerr flush cout before the characters are written. cout doesn't set up a tie to cerr because cerr has the flag ios::unitbuf set, so it flushes itself after every write operation.

Results:

Both forms of the tie() public member function return the previous tie value.

ios::unsetf()

turn off bits in the format flags for the object

Synopsis:

#include <iostream.h>
public:
ios::fmtflags ios::unsetf( ios::fmtflags offbits );

Semantics:

The unsetf() public member function is used to turn off bits in ios::fmtflags that are set in the offbits parameter. All other bits in ios::fmtflags are unchanged.

Results:

The unsetf() public member function returns the old ios::fmtflags value.

ios::width()

query and/or set the format width

Synopsis:

#include <iostream.h>
public:
int ios::width() const;
int ios::width( int wid );

Semantics:

The width() public member function is used to query and/or set the format width used to format the next item. A format width of zero indicates that the item is to be written using exactly the number of positions required. Other values indicate that the item must occupy at least that many positions. If the formatted item is larger than the specified format width, the format width is ignored and the item is formatted using the required number of positions.

The first form of the width() public member function is used to query the format width that's to be used for the next item.

The second form of the function is used to set the format width to wid for the next item to be formatted.

After an item has been formatted, the format width is reset to zero. Therefore, any non-zero format width must be set before each item that's to be formatted.

Results:

The width() public member function returns the previous format width.

ios::xalloc()

return an index into a general-purpose array

Synopsis:

#include <iostream.h>
public:
static int ios::xalloc();

Semantics:

The xalloc() public static member function returns an index into an array of items that the program may use for any purpose. Each item can be either a long int or a pointer to void. The index can be used with the iword() and pword() member functions.

Because the xalloc() public static member function manipulates static member data, its behavior isn't tied to any one object, but affects the entire class of objects. The value that's returned by the xalloc() public static member function is valid for all objects of all classes derived from the ios class. No subsequent call to the xalloc() public static member function will return the same value as a previous call.

Results:

The xalloc() public static member function returns an index for use with the iword() and pword() member functions.

`iostream` Class

Declared:

iostream.h

Derived from:

istream, ostream

Derived by:

fstream, strstream

The iostream class supports the reading and writing of characters from and to the standard input/output devices, usually the keyboard and screen. The iostream class provides formatted conversion of characters to and from other types (for example, integers and floating-point numbers). The associated streambuf class provides the methods for communicating with the actual device, while the iostream class provides the interpretation of the characters.

Generally, an iostream object won't be created by a program, since there's no mechanism at this level to ``open'' a device. No instance of an iostream object is created by default, since it's usually not possible to perform both input and output on the standard input/output devices. The iostream class is provided as a base class for other derived classes that can provide both input and output capabilities through the same object. The fstream and strstream classes are examples of classes derived from the iostream class.

Protected Member Functions

The following protected member functions are declared:

iostream();

Public Member Functions

The following public member functions are declared:

iostream( ios const & );
iostream( streambuf * );
virtual ~iostream();

Public Member Operators

The following public member operators are declared:

iostream & operator =( streambuf * );
iostream & operator =( ios const & );

iostream::iostream()

create a iostream object

Synopsis:

#include <iostream.h>
protected:
iostream::iostream();

public:
iostream::iostream( ios const &strm );
iostream::iostream( streambuf *sb );

Semantics:

There are three forms of the iostream constructor:

The first form is protected member function. It creates an iostream object without an attached streambuf object.
This form of the constructor is only used implicitly by the compiler when it generates a constructor for a derived class.
The second form is a public member function. It creates an iostream object associated with the streambuf object currently associated with the strm parameter. The iostream object is initialized, and uses the strm streambuf object for subsequent operations. strm continues to use the streambuf object.
The third form is also a public member function. It creates an iostream object with an attached streambuf object.
Since a user program usually won't create an iostream object, this form of the public iostream constructor is unlikely to be explicitly used, except in the member initializer list for the constructor of a derived class. The sb parameter is a pointer to a streambuf object, which should be connected to the source and sink of characters for the stream.

Results:

The first (protected) form of the iostream constructor produces an initialized iostream object. ios::badbit is set in the error state in the inherited ios object.
The second (public) form produces an initialized iostream object. If there's no streambuf object currently associated with the strm parameter, ios::badbit is set in the error state in the inherited ios object.
The third (public) form produces an initialized iostream object. If the sb parameter is NULL, ios::badbit is set in the error state in the inherited ios object.

iostream::~iostream()

destroy a iostream object

Synopsis:

#include <iostream.h>
public:
virtual iostream::~iostream();

Semantics:

The public iostream destructor doesn't do anything explicit. The ios destructor is called for that portion of the iostream object. The call to the public iostream destructor is inserted implicitly by the compiler at the point where the iostream object goes out of scope.

Results:

The iostream object is destroyed.

iostream::operator =()

initialize the iostream object

Synopsis:

#include <iostream.h>
public:
iostream &iostream::operator =( streambuf *sb );
iostream &iostream::operator =( const ios &strm );

Semantics:

There are two forms of the operator =() public member function:

The first initializes the target iostream object, and sets up an association between the iostream object and the streambuf object specified by the sb parameter.
The second form initializes the iostream object and sets up an association between the iostream object and the streambuf object currently associated with the strm parameter.

Results:

The operator =() public member function returns a reference to the iostream object that's the target of the assignment.

For the first form, if the sb parameter is NULL, ios::badbit is set in the error state in the inherited ios object.
For the second form, if there's no streambuf object currently associated with the strm parameter, ios::badbit is set in the error state in the inherited ios object.

`istream` Class

Declared:

iostream.h

Derived from:

ios

Derived by:

iostream, ifstream, istrstream

The istream class supports reading characters from a class derived from streambuf, and provides formatted conversion of characters into other types (such as integers and floating-point numbers). The streambuf class provides the methods for communicating with the external device (keyboard, disk), while the istream class provides the interpretation of the resulting characters.

Generally, an istream object won't be explicitly created by a program, since there's no mechanism at this level to open a device. The only default istream object in a program is cin, which reads from standard input (usually the keyboard).

The istream class supports two basic concepts of input: formatted and unformatted. The overloaded operator >>() member functions are called extractors, and they provide the support for formatted input. The rest of the member functions deal with unformatted input, managing the state of the ios object and providing a friendlier interface to the associated streambuf object.

Protected Member Functions

The following protected member functions are declared:

istream();
eatwhite();

Public Member Functions

The following public member functions are declared:

istream( istream const & );
istream( streambuf * );
virtual ~istream();
int ipfx( int = 0 );
void isfx();
int get();
istream &get(          char *, int, char = '\n' );
istream &get(   signed char *, int, char = '\n' );
istream &get( unsigned char *, int, char = '\n' );
istream &get(          char & );
istream &get(   signed char & );
istream &get( unsigned char & );
istream &get( streambuf &, char = '\n' );
istream &getline(      char *, int, char = '\n' );
istream &getline(   signed char *, int, char = '\n' );
istream &getline( unsigned char *, int, char = '\n' );
istream &ignore( int = 1, int = EOF );
istream &read(           char *, int );
istream &read(    signed char *, int );
istream &read( unsigned char *, int );
istream &seekg( streampos );
istream &seekg( streamoff, ios::seekdir );
istream &putback( char );
streampos tellg();
int gcount() const;
int peek();
int sync();

Public Member Operators

The following public member operators are declared:

istream &operator =( streambuf * );
istream &operator =( istream const & );
istream &operator >>(        char * );
istream &operator >>(   signed char * );
istream &operator >>( unsigned char * );
istream &operator >>(        char & );
istream &operator >>(   signed char & );
istream &operator >>( unsigned char & );
istream &operator >>(   signed short & );
istream &operator >>( unsigned short & );
istream &operator >>(   signed int & );
istream &operator >>( unsigned int & );
istream &operator >>(   signed long & );
istream &operator >>( unsigned long & );
istream &operator >>(     float & );
istream &operator >>(    double & );
istream &operator >>( long double & );
istream &operator >>( streambuf & );
istream &operator >>( istream &(*)( istream & ) );
istream &operator >>(     ios &(*)( ios     & ) );

istream::eatwhite()

discard whitespace characters

Synopsis:

#include <iostream.h>
protected:
void istream::eatwhite();

Semantics:

The eatwhite() protected member function extracts and discards whitespace characters from the istream object until a non-whitespace character is found. The non-whitespace character isn't extracted.

Results:

The eatwhite() protected member function sets ios::eofbit in the error state in the inherited ios object if end-of-file is encountered as the first character while extracting whitespace characters.

istream::gcount()

determine the number of characters most recently extracted

Synopsis:

#include <iostream.h>
public:
int istream::gcount() const;

Semantics:

The gcount() public member function determines the number of characters extracted by the last unformatted input member function.

Results:

The gcount() public member function returns the number of characters extracted by the last unformatted input member function.

istream::get()

perform an unformatted read

Synopsis:

#include <iostream.h>
public:

// return a character
int istream::get();

// read a character
istream &istream::get(          char &ch );
istream &istream::get(   signed char &ch );
istream &istream::get( unsigned char &ch );

// read a number of characters
istream &istream::get( char *buf, int len,
             char delim = '\n' );
istream &istream::get( signed char *buf, int len,
             char delim = '\n' );
istream &istream::get( unsigned char *buf, int len,
             char delim = '\n' );

// read until a given delimiter is found
istream &istream::get( streambuf &sb, 
                       char delim = '\n' );

Semantics:

The get() public member function performs an unformatted read. The arguments determine what is read.

Return a character

This form of the get() public member function performs an unformatted read of a single character from the istream object.

Read a character

These forms of the get() public member function perform an unformatted read of a single character from the istream object and store the character in the ch parameter.

Read a number of characters

These forms of the get() public member function perform an unformatted read of at most len -1 characters from the istream object, and store them starting at the memory location specified by the buf parameter. If the character specified by the delim parameter is encountered in the istream object before len -1 characters have been read, the read terminates without extracting the delimiting character.

After the read terminates, whether or not an error occurred, a null character is stored in buf following the last character read from the istream object.

If the delim parameter isn't specified, the new-line character is assumed.

Read until a given delimiter is found

This form of the get() public member function performs an unformatted read of characters from the istream object and transfers them to the streambuf object specified in the sb parameter. The transfer stops if end-of-file is encountered, the delimiting character specified in the delim parameter is found, or if the store into the sb parameter fails. If the delim character is found, it isn't extracted from the istream object and isn't transferred to the sb object.

If the delim parameter isn't specified, the new-line character is assumed.

Results:

Return a character

This form of the get() public member function returns the character read from the istream object. If the istream object is positioned at end-of-file before the read, EOF is returned and ios::eofbit bit is set in the error state in the inherited ios object. ios::failbit bit isn't set by this form of the get() public member function.

Read a character

These forms of the get() public member function return a reference to the istream object. ios::eofbit is set in the error state in the inherited ios object if the istream object is positioned at end-of-file before the attempt to read the character. ios::failbit is set in the error state in the inherited ios object if no character is read.

Read a number of characters

These forms of the get() public member function return a reference to the istream object. If end-of-file is encountered as the first character, ios::eofbit is set in the error state in the inherited ios object. If no characters are stored into buf, ios::failbit is set in the error state in the inherited ios object.

Read until a given delimiter is found

This form of the get() public member function returns a reference to the istream object. ios::failbit is set in the error state in the inherited ios object if the store into the streambuf object fails.

istream::getline()

read a line of characters

Synopsis:

#include <iostream.h>
public:
istream &istream::getline( char *buf, 
                 int len, char delim = '\n' );
istream &istream::getline( signed char *buf,
                 int len, char delim = '\n' );
istream &istream::getline( unsigned char *buf,
                 int len, char delim = '\n' );

Semantics:

The getline() public member function performs an unformatted read of at most len -1 characters from the istream object, and stores them starting at the memory location specified by the buf parameter. If the delimiting character, specified by the delim parameter, is encountered in the istream object before len -1 characters have been read, the read terminates after extracting the delim character.

If len -1 characters have been read and the next character is the delim character, it isn't extracted.

After the read terminates, whether or not an error occurred, a null character is stored in the buffer following the last character read from the istream object.

If the delim parameter isn't specified, the new-line character is assumed.

Results:

The getline() public member function returns a reference to the istream object. If end-of-file is encountered as the first character, ios::eofbit is set in the error state in the inherited ios object. If end-of-file is encountered before len characters are transferred or the delim character is reached, ios::failbit is set in the error state in the inherited ios object.

istream::ignore()

discard a given number of characters

Synopsis:

#include <iostream.h>
public:
istream &istream::ignore( int num = 1, 
                          int delim = EOF );

Semantics:

The ignore() public member function extracts and discards up to num characters from the istream object. If the num parameter isn't specified, this function extracts and discards one character. If the delim parameter isn't EOF and it's encountered before num characters have been extracted, the extraction ceases after discarding the delimiting character. The extraction stops if end-of-file is encountered.

If the num parameter is specified as a negative number, no limit is imposed on the number of characters extracted and discarded. The operation continues until the delimiting character is found and discarded, or until end-of-file. This behavior is a WATCOM extension.

Results:

The ignore() public member function returns a reference to the istream object. If end-of-file is encountered as the first character, ios::eofbit is set in the error state in the inherited ios object.

istream::ipfx()

a prefix function that's executed before any read operation

Synopsis:

#include <iostream.h>
public:
int istream::ipfx( int noskipws = 0 );

Semantics:

The ipfx() public member function is a prefix function that's executed before each of the formatted and unformatted read operations. If any bits are set in ios::iostate, the ipfx() public member function immediately returns 0, indicating that the prefix function failed. Failure in the prefix function causes the input operation to fail.

If the noskipws parameter is 0 or unspecified and the ios::skipws bit is on in ios::fmtflags, whitespace characters are discarded and the istream object is positioned so that the next character read is the first character after the discarded whitespace. Otherwise, no whitespace skipping takes place.

The formatted input functions that read specific types of objects (such as integers and floating-point numbers) call the ipfx() public member function with the noskipws parameter set to zero, allowing leading whitespaces to be discarded if the ios::skipws bit is on in ios::fmtflags. The unformatted input functions that read characters without interpretation call the ipfx() public member function with a the noskipws parameter set to 1 so that no whitespace characters are discarded.

If the istream object is tied to an output stream, the output stream is flushed.

Results:

If the istream object isn't in an error state in the inherited ios object when the above processing is completed, the ipfx() public member function returns a non-zero value to indicate success. Otherwise, zero is returned to indicate failure.

istream::isfx()

a suffix function that's called after any read operation

Synopsis:

#include <iostream.h>
public:
void istream::isfx();

Semantics:

The isfx() public member function is a suffix function executed just before the end of each of the formatted and unformatted read operations.

As currently implemented, the isfx() public member function doesn't do anything.

istream::istream()

create a istream object

Synopsis:

#include <iostream.h>
protected:
istream::istream();

public:
istream::istream( istream const &istrm );
istream::istream( streambuf *sb );

Semantics:

There are three forms of the istream constructor:

The first form is a protected member function. It creates an istream object without an associated streambuf object.
This form of the protected istream constructor is only used implicitly by the compiler when it generates a constructor for a derived class.
The second form is a public member function. It creates an istream object associated with the streambuf object currently associated with the istrm parameter. The istream object is initialized and uses the istrm streambuf object for subsequent operations. istrm continues to use the streambuf object.
The third form is also a public member function. It creates an istream object with an associated streambuf object specified by the sb parameter.
This function is likely to be used for the creation of an istream object that's associated with the same streambuf object as another istream object.

Results:

The first (protected) form of the istream constructor creates an initialized istream object. ios::badbit is set in the error state in the inherited ios object.
The second (public) form creates an initialized istream object. If there's no streambuf object currently associated with the istrm parameter, ios::badbit is set in the error state in the inherited ios object.
This form of the public istream constructor creates an initialized istream object. If the sb parameter is NULL, ios::badbit is set in the error state in the inherited ios object.

istream::~istream()

destroy a istream object

Synopsis:

#include <iostream.h>
public:
virtual istream::~istream();

Semantics:

The public virtual istream destructor doesn't do anything explicit. The ios destructor is called for that portion of the istream object. The call to the public virtual istream destructor is inserted implicitly by the compiler at the point where the istream object goes out of scope.

Results:

The istream object is destroyed.

istream::operator =()

associate a streambuf object with the istream object

Synopsis:

#include <iostream.h>
public:
istream &istream::operator =( streambuf *sb );
istream &istream::operator =( 
    istream const &istrm );

Semantics:

There are two forms of the operator =() public member function:

The first is used to associate a streambuf object, specified by the sb parameter, with an existing istream object. The istream object is initialized, and uses the specified streambuf object for subsequent operations.
The second form is used to associate the istream object with the streambuf object currently associated with the istrm parameter. The istream object is initialized, and uses the istrm 's streambuf object for subsequent operations. The istrm object continues to use the streambuf object.

Results:

The first form of the operator =() public member function returns a reference to the istream object that's the target of the assignment. If the sb parameter is NULL, ios::badbit is set in the error state in the inherited ios object.
The second form returns a reference to the istream object that's the target of the assignment. If there's no streambuf object currently associated with the istrm parameter, ios::badbit is set in the error state in the inherited ios object.

istream::operator >>()

read characters

Synopsis:

#include <iostream.h>
public:

// read characters
istream &istream::operator >>
    (          char *buf );
istream &istream::operator >>
    (   signed char *buf );
istream &istream::operator >>
    ( unsigned char *buf );

// read a single character
istream &istream::operator >>
    (          char &ch );
istream &istream::operator >>
    (   signed char &ch );
istream &istream::operator >>
    ( unsigned char &ch );

// read an integer
istream &istream::operator >>
    (   signed    int &num );
istream &istream::operator >>
    ( unsigned    int &num );
istream &istream::operator >>
    (   signed  long &num );
istream &istream::operator >>
    ( unsigned  long &num );
istream &istream::operator >>
    (   signed short &num );
istream &istream::operator >>
    ( unsigned short &num );

// read a floating-point value
istream &istream::operator >>
    (       float &num );
istream &istream::operator >>
    (      double &num );
istream &istream::operator >>
    ( long double &num );

// read until end-of-file
istream &istream::operator >>( streambuf &sb );

// call a non-parameterized manipulator
istream &istream::operator >>
    ( istream &(*fn)( istream & ) );
istream &istream::operator >>
    (     ios &(*fn)( ios     & ) );

Semantics:

The operator >>() public member function performs a formatted read. The parameters determine what's read.

Characters

These forms of the operator >>() public member function perform a formatted read of characters from the istream object and place them in the buffer specified by the buf parameter. Characters are read until a whitespace character is found or the maximum size has been read. If a whitespace character is found, it isn't transferred to the buffer, and remains in the istream object.

If a non-zero format width has been specified, it's interpreted as the maximum number of characters that may be placed in buf. No more than format width-1 characters are read from the istream object and transferred to buf. If format width is zero, characters are transferred until a whitespace character is found.

Since these forms of the operator >>() public member function use format width, it's reset to zero after each use. It must be set before each input operation that requires a non-zero format width.

A null character is added following the last transferred character, even if the transfer fails because of an error.

Single character

These forms of the operator >>() public member function perform a formatted read of a single character from the istream object and place it in the ch parameter.

Integer

These forms the operator >>() public member function perform a formatted read of an integral value from the istream object, and place it in the num parameter.

The number may be preceded by a + or - sign.

If ios::dec is the only bit set in the ios::basefield bits of ios::fmtflags, the number is interpreted as a decimal (base 10) integer, composed of the digits 0123456789.

If ios::oct is the only bit set in the ios::basefield bits of ios::fmtflags, the number is interpreted as an octal (base 8) integer, composed of the digits 01234567.

If ios::hex is the only bit set in the ios::basefield bits of ios::fmtflags, the number is interpreted as a hexadecimal (base 16) integer, composed of the digits 0123456789 and the letters abcdef or ABCDEF.

If no bits are set in the ios::basefield bits of ios::fmtflags, the operator looks for a prefix to determine the base of the number. If the first two characters are 0x or 0X, the number is interpreted as a hexadecimal number. If the first character is a 0 (and the second isn't an x or X), the number is interpreted as an octal integer. Otherwise, no prefix is expected, and the number is interpreted as a decimal integer.

If more than one bit is set in the ios::basefield bits of ios::fmtflags, the number is interpreted as a decimal integer.

Floating-point

These forms of the operator >>() public member function perform a formatted read of a floating-point value from the istream object and place it in the num parameter.

The floating-point value may be specified in any form that's acceptable to the C++ compiler.

Read until end-of-file

This form of the operator >>() public member function transfers all the characters from the istream object into the sb parameter. Reading continues until end-of-file is encountered.

Read with a manipulator

These forms of the operator >>() public member function are used to implement the non-parameterized manipulators for the istream class. The function specified by the fn parameter is called with the istream object as its parameter.

Results:

Characters

These forms of the operator >>() public member function return a reference to the istream object so that further extraction operations may be specified in the same statement. If no characters are transferred to buf, ios::failbit is set in the error state in the inherited ios object. If the first character read yielded end-of-file, ios::eofbit is set in the error state in the inherited ios object.

Single character

Integer

These forms of the operator >>() public member function return a reference to the istream object so that further extraction operations may be specified in the same statement. If end-of-file is encountered as the first character, ios::eofbit is set in the error state in the inherited ios object. If an overflow occurs while converting to the required integer type, the ios::failbit is set in the error state in the inherited ios object.

Floating-point

These forms of the operator >>() public member function return a reference to the istream object so that further extraction operations may be specified in the same statement. If end-of-file is encountered as the first character, ios::eofbit is set in the error state in the inherited ios object. If an overflow occurs while converting to the required type, the ios::failbit is set in the error state in the inherited ios object.

Read until end-of-file

This form of the operator >>() public member function returns a reference to the istream object, so that further extraction operations may be specified in the same statement.

Read with a manipulator

These forms of the operator >>() public member function return a reference to the istream object so that further extraction operations may be specified in the same statement.

istream::peek()

look up the next character, without extracting it

Synopsis:

#include <iostream.h>
public:
int istream::peek();

Semantics:

The peek() public member function looks up the next character to be extracted from the istream object, without extracting it.

Results:

The peek() public member function returns the next character to be extracted from the istream object. If the istream object is positioned at end-of-file, EOF is returned.

istream::putback()

try to put the extracted character back into the istream object

Synopsis:

#include <iostream.h>
public:
istream &istream::putback( char ch );

Semantics:

The putback() public member function attempts to put the extracted character specified by the ch parameter back into the istream object. The ch character must be the same as the character before the current position of the istream object, usually the last character extracted from the stream. If it isn't the same character, the result of the next character extraction is undefined.

The number of characters that can be put back is defined by the istream object, but is usually at least 4. Depending on the status of the buffers used for input, it might be possible to put back more than 4 characters.

Results:

The putback() public member function returns a reference to the istream object. If the putback() public member function is unable to put back the ch parameter, ios::failbit is set in the error state in the inherited ios object.

istream::read()

read a number of characters

Synopsis:

#include <iostream.h>
public:
istream &istream::read
    ( char *buf, int len );
istream &istream::read
    ( signed char *buf, int len );
istream &istream::read
    ( unsigned char *buf, int len );

Semantics:

The read() public member function performs an unformatted read of at most len characters from the istream object and stores them in the memory locations starting at buf. If end-of-file is encountered before len characters have been transferred, the transfer stops and ios::failbit is set in the error state in the inherited ios object.

The number of characters extracted can be determined with the gcount() member function.

Results:

The read() public member function returns a reference to the istream object. If end-of-file is encountered as the first character, ios::eofbit is set in the error state in the inherited ios object. If end-of-file is encountered before len characters are transferred, ios::failbit is set in the error state in the inherited ios object.

istream::seekg()

position the istream object

Synopsis:

#include <iostream.h>
public:
istream &istream::seekg( streampos pos );
istream &istream::seekg( streamoff offset, 
                         ios::seekdir dir );

Semantics:

There are two forms of the seekg() public member function:

The first positions the istream object to the position specified by the pos parameter so that the next input operation commences from that position.
The second form positions the istream object to the specified position so that the next input operation commences from that position.
The dir parameter may be ios::beg, ios::cur or ios::end, and is interpreted in conjunction with the offset parameter as follows:

ios::beg
the offset is relative to the start, and should be a positive value.
ios::cur
the offset is relative to the current position, and may be positive (seek towards end) or negative (seek towards start).
ios::end
the offset is relative to the end, and should be a negative value.

If the dir parameter has any other value, or the offset parameter doesn't have an appropriate sign, the seekg() public member function fails.

Results:

The seekg() public member function returns a reference to the istream object. If the seek operation fails, ios::failbit is set in the error state in the inherited ios object.

istream::sync()

synchronize the istream and the source of characters

Synopsis:

#include <iostream.h>
public:
int istream::sync();

Semantics:

The sync() public member function synchronizes the input buffer and the istream object with whatever source of characters is being used. The sync() public member function uses the streambuf class's sync() virtual member function to carry out the synchronization. The specific behavior depends on what type of streambuf-derived object is associated with the istream object.

Results:

The sync() public member function returns __NOT_EOF on success, otherwise EOF is returned.

istream::tellg()

determine the position of the next available character

Synopsis:

#include <iostream.h>
public:
streampos istream::tellg();

Semantics:

The tellg() public member function determines the position in the istream object of the next character available for reading. The first character in an istream object is at offset zero.

Results:

The tellg() public member function returns the position of the next character available for reading.

`istrstream` Class

Declared:

strstrea.h

Derived from:

strstreambase, istream

The istrstream class is used to create and read from string stream objects.

The istrstream class provides little of its own functionality. Derived from the strstreambase and istream classes, its constructors and destructor provide simplified access to the appropriate equivalents in those base classes.

Of the available I/O stream classes, creating an istrstream object is the preferred method of performing read operations from a string stream.

Public Member Functions

The following member functions are declared in the public interface:

istrstream(          char * );
istrstream(   signed char * );
istrstream( unsigned char * );
istrstream(          char *, int );
istrstream(   signed char *, int );
istrstream( unsigned char *, int );
~istrstream();

istrstream::istrstream()

create a istrstream object

Synopsis:

#include <strstrea.h>
public:
istrstream::istrstream( char *str );
istrstream::istrstream( signed char *str );
istrstream::istrstream( unsigned char *str );

istrstream::istrstream( char *str, int len );
istrstream::istrstream( signed char *str, 
                        int len );
istrstream::istrstream( unsigned char *str, 
                        int len );

Semantics:

There are six forms of the public istrstream constructor:

The first three forms create an istrstream object consisting of the null-terminated C string specified by the str parameter. The inherited istream member functions can be used to read from the istrstream object.
The other three forms create an istrstream object consisting of the characters starting at str and ending at str + len - 1. The inherited istream member functions can be used to read from the istrstream object.

Results:

The public istrstream constructor creates an initialized istrstream object.

istrstream::~istrstream()

destroy a istrstream object

Synopsis:

#include <strstrea.h>
public:
istrstream::~istrstream();

Semantics:

The public istrstream destructor doesn't do anything explicit. The call to this destructor is inserted implicitly by the compiler at the point where the istrstream object goes out of scope.

Results:

The istrstream object is destroyed.

Manipulators

Declared:

iostream.h and iomanip.h

Manipulators are designed to be inserted into or extracted from a stream. Manipulators come in two forms, non-parameterized and parameterized. The non-parameterized manipulators are simpler, and are declared in iostream.h. The parameterized manipulators are more complex, and are declared in iomanip.h.

iomanip.h defines two macros, SMANIP_define() and SMANIP_make() to implement parameterized manipulators. The workings of these macros are disclosed in the header file, and aren't discussed here.

Non-parameterized Manipulators

The following non-parameterized manipulators are declared in iostream.h:

ios &dec( ios & );
ios &hex( ios & );
ios &oct( ios & );
istream &ws( istream & );
ostream &endl( ostream & );
ostream &ends( ostream & );
ostream &flush( ostream & );

Parameterized Manipulators

The following parameterized manipulators are declared in iomanip.h:

SMANIP_define( long ) resetiosflags( long );
SMANIP_define( int )  setbase( int );
SMANIP_define( int )  setfill( int );
SMANIP_define( long ) setiosflags( long );
SMANIP_define( int )  setprecision( int );
SMANIP_define( int )  setw( int );
SMANIP_define( int )  setwidth( int );

manipulator dec()

specify decimal formatting

Synopsis:

#include <iostream.h>
ios &dec( ios &strm );

Semantics:

The dec() manipulator sets the ios::basefield bits for decimal formatting in ios::fmtflags in the strm ios object.

manipulator endl()

write a new-line character, and flush

Synopsis:

#include <iostream.h>
ostream &endl( ostream &ostrm );

Semantics:

The endl() manipulator writes a new-line character to the stream specified by the ostrm parameter and performs a flush.

manipulator ends()

write a null character to the stream

Synopsis:

#include <iostream.h>
ostream &ends( ostream &ostrm );

Semantics:

The ends() manipulator writes a null character to the stream specified by the ostrm parameter.

manipulator flush()

flush the stream

Synopsis:

#include <iostream.h>
ostream &flush( ostream &ostrm );

Semantics:

The flush() manipulator flushes the stream specified by the ostrm parameter. The flush is performed in the same manner as the ostream::flush() member function.

manipulator hex()

specify hexadecimal formatting

Synopsis:

#include <iostream.h>
ios &hex( ios &strm );

Semantics:

The hex() manipulator sets the ios::basefield bits for hexadecimal formatting in ios::fmtflags in the strm ios object.

manipulator oct()

specify octal formatting

Synopsis:

#include <iostream.h>
ios &oct( ios &strm );

Semantics:

The oct() manipulator sets the ios::basefield bits for octal formatting in ios::fmtflags in the strm ios object.

manipulator resetiosflags()

reset formatting flags

Synopsis:

#include <iomanip.h>
SMANIP_define( long ) resetiosflags( long flags )

Semantics:

The resetiosflags() manipulator turns off the bits in ios::fmtflags that correspond to the bits that are on in the flags parameter. No other bits are affected.

manipulator setbase()

set the base

Synopsis:

#include <iomanip.h>
SMANIP_define( int ) setbase( int base );

Semantics:

The setbase() manipulator sets the ios::basefield bits in ios::fmtflags to the value specified by the base parameter within the stream that the setbase() manipulator is operating upon.

manipulator setfill()

set the fill character

Synopsis:

#include <iomanip.h>
SMANIP_define( int ) setfill( int fill )

Semantics:

The setfill() manipulator sets the fill character to the value specified by the fill parameter within the stream that the setfill() manipulator is operating upon.

manipulator setiosflags()

set formatting flags

Synopsis:

#include <iomanip.h>
SMANIP_define( long ) setiosflags( long flags );

Semantics:

The setiosflags() manipulator turns on the bits in ios::fmtflags that correspond to the bits that are on in the flags parameter. No other bits are affected.

manipulator setprecision()

set the format precision

Synopsis:

#include <iomanip.h>
SMANIP_define( int ) setprecision( int prec );

Semantics:

The setprecision() manipulator sets the format precision to the value specified by the prec parameter within the stream that the setprecision() manipulator is operating upon.

manipulator setw()

set the format width

Synopsis:

#include <iomanip.h>
SMANIP_define( int ) setw( int wid );

Semantics:

The setw() manipulator sets the format width to the value specified by the wid parameter within the stream that the setw() manipulator is operating upon.

manipulator setwidth()

set the format width

Synopsis:

#include <iomanip.h>
SMANIP_define( int ) setwidth( int wid );

Semantics:

The setwidth() manipulator sets the format width to the value specified by the wid parameter within the stream that the setwidth() manipulator is operating upon.

This function is a WATCOM extension.

manipulator ws()

extract and discard whitespace characters

Synopsis:

#include <iostream.h>
istream &ws( istream &istrm );

Semantics:

The ws() manipulator extracts and discards whitespace characters from the istrm parameter, leaving the stream positioned at the next non-whitespace character.

The ws() manipulator is needed particularly when the ios::skipws bit isn't set in ios::fmtflags in the istrm object. In this case, whitespace characters must be explicitly removed from the stream, since the formatted input operations won't automatically remove them.

`ofstream` Class

Declared:

fstream.h

Derived from:

fstreambase, ostream

The ofstream class is used to create new files or access existing files for writing. The file can be opened and closed, and write and seek operations can be performed.

The ofstream class provides very little of its own functionality. Derived from both the fstreambase and ostream classes, its constructors, destructor and member function provide simplified access to the appropriate equivalents in those base classes.

Of the available I/O stream classes, creating an ofstream object is the preferred method of accessing a file for output operations.

Public Member Functions

The following public member functions are declared:

ofstream();
ofstream( char const *,
        ios::openmode = ios::out,
        int = filebuf::openprot );
ofstream( filedesc );
ofstream( filedesc, char *, int );
~ofstream();
void open( char const *,
         ios::openmode = ios::out,
         int = filebuf::openprot );

ofstream::ofstream()

create a ofstream object

Synopsis:

#include <fstream.h>
public:
ofstream::ofstream();
ofstream::ofstream( const char *name,
              ios::openmode mode = ios::out,
              int prot = filebuf::openprot );
ofstream::ofstream( filedesc hdl );
ofstream::ofstream( filedesc hdl, char *buf, 
                    int len );

Semantics:

There are four forms of the public ofstream constructor:

The first creates an ofstream object that isn't connected to a file. The open() or attach() member functions should be used to connect the ofstream object to a file.
The second form creates an ofstream object that's connected to the file specified by the name parameter, using the specified mode and prot parameters. The connection is made via the C library open() function.
The thrid form creates an ofstream object that's attached to the file specified by the hdl parameter.
The fourth form creates an ofstream object that's connected to the file specified by the hdl parameter. The buffer specified by the buf and len parameters is offered to the associated filebuf object via the setbuf() member function.
If thebuf parameter is NULL or the len is less than or equal to zero, the filebuf is unbuffered, so that each read or write operation reads or writes a single character at a time.

Results:

The first form of the public ofstream constructor produces an ofstream object that isn't connected to a file.
The second form produces an ofstream object that's connected to the file specified by name. If the open() fails, ios::failbit and ios::badbit are set in the error state in the inherited ios object.
The third form produces an ofstream object that's attached to hdl. If the attach fails, ios::failbit and ios::badbit are set in the error state in the inherited ios object.
The fourth form produces an ofstream object that's attached to hdl. If the connection to hdl fails, ios::failbit and ios::badbit are set in the error state in the inherited ios object. If the setbuf() fails, ios::failbit is set in the error state in the inherited ios object.

ofstream::~ofstream()

destroy a ofstream object

Synopsis:

#include <fstream.h>
public:
ofstream::~ofstream();

Semantics:

The public ofstream destructor doesn't do anything explicit. The call to this destructor is inserted implicitly by the compiler at the point where the ofstream object goes out of scope.

Results:

The ofstream object is destroyed.

ofstream::open()

connect the ofstream object to a file

Synopsis:

#include <fstream.h>
public:
void ofstream::open( const char *name,
            ios::openmode mode = ios::out,
            int prot = filebuf::openprot );

Semantics:

The open() public member function connects the ofstream object to the file specified by the name parameter, using the specified mode and prot parameters.

The mode parameter is optional, and usually isn't specified unless additional bits (such as ios::binary or ios::text) are to be specified. The connection is made via the C library open() function.

Results:

If the open() fails, ios::failbit is set in the error state in the inherited ios object.

`ostream` Class

Declared:

iostream.h

Derived from:

ios

Derived by:

iostream, ofstream, ostrstream

The ostream class supports writing characters to a class derived from the streambuf class, and provides formatted conversion of types (such as integers and floating-point numbers) into characters. The class derived from the streambuf class provides the methods for communicating with the external device (screen, disk), while the ostream class provides the conversion of the types into characters.

Generally, ostream objects won't be explicitly created by a program, since there is no mechanism at this level to open a device. The only default ostream objects in a program are cout, cerr and clog, which write to the standard output and error devices (usually the screen).

The ostream class supports two basic concepts of output: formatted and unformatted. The overloaded operator <<() member functions are called inserters, and they provide the support for formatted output. The rest of the member functions deal with unformatted output, managing the state of the ios object, and providing a friendlier interface to the associated streambuf object.

Protected Member Functions

The following protected member functions are declared:

ostream();

Public Member Functions

The following public member functions are declared:

ostream( ostream const & );
ostream( streambuf * );
virtual ~ostream();
ostream &flush();
int opfx();
void osfx();
ostream &put(          char );
ostream &put(   signed char );
ostream &put( unsigned char );
ostream &seekp( streampos );
ostream &seekp( streamoff, ios::seekdir );
streampos tellp();
ostream &write(        char const *, int );
ostream &write(     signed char const *, int );
ostream &write( unsigned char const *, int );

Public Member Operators

The following public member operators are declared:

ostream &operator =( streambuf * );
ostream &operator =( ostream const & );
ostream &operator <<(        char );
ostream &operator <<(   signed char );
ostream &operator <<( unsigned char );
ostream &operator <<(   signed short );
ostream &operator <<( unsigned short );
ostream &operator <<(   signed int );
ostream &operator <<( unsigned int );
ostream &operator <<(   signed long );
ostream &operator <<( unsigned long );
ostream &operator <<(    float );
ostream &operator <<(    double );
ostream &operator <<( long double );
ostream &operator <<( void * );
ostream &operator <<( streambuf & );
ostream &operator <<(        char const * );
ostream &operator <<(   signed char const * );
ostream &operator <<( unsigned char const * );
ostream &operator <<( ostream &(*)( ostream & ) );
ostream &operator <<( ios       &(*)( ios     & ) );

ostream::flush()

flush the ostream object's buffers

Synopsis:

#include <iostream.h>
public:
ostream &ostream::flush();

Semantics:

The flush() public member function causes the ostream object's buffers to be flushed, forcing the contents to be written to the actual device connected to the ostream object.

Results:

The flush() public member function returns a reference to the ostream object. On failure, ios::failbit is set in the error state in the inherited ios object.

ostream::operator <<()

perform a formatted write

Synopsis:

#include <iostream.h>
public:

// write a character
ostream &ostream::operator <<(          char ch );
ostream &ostream::operator <<(   signed char ch );
ostream &ostream::operator <<( unsigned char ch );

// write a string
ostream &ostream::operator <<(
     char const *str );
ostream &ostream::operator <<(   
    signed char const *str );
ostream &ostream::operator <<(
     unsigned char const *str );

// write an integer
ostream &ostream::operator <<( 
    signed int num );
ostream &ostream::operator <<( 
    unsigned int num );
ostream &ostream::operator <<( 
    signed long num );
ostream &ostream::operator <<( 
    unsigned long num );
ostream &ostream::operator <<( 
    signed short num );
ostream &ostream::operator <<( 
    unsigned short num );

// write a floating-point number
ostream &ostream::operator <<(       float num );
ostream &ostream::operator <<(      double num );
ostream &ostream::operator <<( long double num );

// write a pointer
ostream &ostream::operator <<( void *ptr );

// write the contents of a stream buffer
ostream &ostream::operator <<( streambuf &sb );

// implement non-parameterized manipulators
ostream &ostream::operator <<( 
    ostream &(*fn)( ostream &) );
ostream &ostream::operator <<( 
    ios     &(*fn)( ios & ) );

Semantics:

The operator <<() public member function does a formatted write into the ostream object. The parameters determine what's being written.

Write a character

These forms of the operator <<() public member function write the ch character into the ostream object.

Write a string

These forms of the operator <<() public member function perform a formatted write of the contents of the C string specified by the str parameter to the ostream object. The characters from str are transferred up to, but not including the terminating null character.

Write an integer

These forms of the operator <<() public member function perform a formatted write of the integral value specified by the num parameter to the ostream object. The integer value is converted to a string of characters which are written to the ostream object.

num is converted to a base representation depending on the setting of the ios::basefield bits in ios::fmtflags. If the ios::oct bit is the only bit on, the conversion is to an octal (base 8) representation. If the ios::hex bit is the only bit on, the conversion is to a hexadecimal (base 16) representation. Otherwise, the conversion is to a decimal (base 10) representation.

For decimal conversions only, a sign may be written in front of the number. If the number is negative, a - minus sign is written. If the number is positive and the ios::showpos bit is on in ios::fmtflags, a + plus sign is written. No sign is written for a value of zero.

If the ios::showbase bit is on in ios::fmtflags, and the conversion is to octal or hexadecimal, the base indicator is written next. The base indicator for a conversion to octal is a zero. The base indicator for a conversion to hexadecimal is 0x or 0X, depending on the setting of the ios::uppercase bit in ios::fmtflags.

If the value being written is zero, the conversion is to octal, and the ios::showbase bit is on, nothing further is written since a single zero is sufficient.

The value of num is then converted to characters:

For conversions to decimal, the magnitude of the number is converted to a string of decimal digits 0123456789.
For conversions to octal, the number is treated as an unsigned quantity, and converted to a string of octal digits 01234567.
For conversions to hexadecimal, the number is treated as an unsigned quantity, and converted to a string of hexadecimal digits 0123456789 and the letters abcdef or ABCDEF, depending on the setting of the ios::uppercase in ios::fmtflags.

The string resulting from the conversion is then written to the ostream object.

If the ios::internal bit is set in ios::fmtflags and padding is required, the padding characters are written after the sign and/or base indicator (if present) and before the digits.

Write a floating-point number

These forms of the operator <<() public member function perform a formatted write of the floating-point value specified by the num parameter to the ostream object. The number is converted to either scientific (exponential) form or fixed-point form, depending on the setting of the ios::floatfield bits in ios::fmtflags:

If ios::scientific is the only bit set, the conversion is to scientific form.
If ios::fixed is the only bit set, the conversion is to fixed-point form.
Otherwise (that is, if neither bit is set, or both are set), the value of the number determines the conversion used. If the exponent is less than -4, or is greater than or equal to the format precision, the scientific form is used. Otherwise, the fixed-point form is used.

Scientific form consists of a minus sign (for negative numbers), one digit, a decimal point, format precision-1 digits, an e or E (depending on the setting of the ios::uppercase bit), a minus sign (for negative exponents) or a plus sign (for zero or positive exponents), and two or three digits for the exponent. The digit before the decimal isn't zero, unless the number is zero. If the format precision is zero (or one), no digits are written following the decimal point.

Fixed-point form consists of a minus sign (for negative numbers), one or more digits, a decimal point, and format precision digits.

If the ios::showpoint bit isn't set in ios::fmtflags, trailing zeroes are trimmed after the decimal point (and before the exponent for scientific form), and if no digits remain after the decimal point, the decimal point is discarded as well.

If the ios::internal bit is set in ios::fmtflags and padding is required, the padding characters are written after the sign (if present) and before the digits.

Write a pointer

This form of the operator <<() public member function performs a formatted write of the pointer value specified by the ptr parameter to the ostream object.

The ptr parameter is converted to an implementation-defined string of characters, and written to the ostream object. With the Watcom C++ implementation, the string starts with 0x or 0X (depending on the setting of the ios::uppercase bit), followed by 4 hexadecimal digits for 16-bit pointers, and 8 hexadecimal digits for 32-bit pointers. Leading zeroes are added to ensure the correct number of digits are written. For far pointers, 4 additional hexadecimal digits and a colon (:) are inserted immediately after the 0x prefix.

Write the contents of a stream buffer

This form of the operator <<() public member function transfers the contents of the sb streambuf object to the ostream object. Reading from the streambuf object stops when the read fails. No padding with the fill character takes place on output to the ostream object.

Implement non-parameterized manipulators

These forms of the operator <<() public member function are used to implement the non-parameterized manipulators for the ostream class. The function specified by the fn parameter is called with the ostream object as its parameter.

Results:

All of the forms of the operator <<() public member function return a reference to the ostream object, so that further insertion operations may be specified in the same statement. ios::failbit is set in the error state in the inherited ios object if an error occurs.

ostream::operator =()

associate a stream buffer with the ostream object

Synopsis:

#include <iostream.h>
public:
ostream &ostream::operator =( 
    streambuf *sb );
ostream &ostream::operator =( 
    const ostream &ostrm );

Semantics:

There are two forms of the operator =() public member function:

The first is used to associate a streambuf object, specified by the sb parameter, with an existing ostream object. The ostream object is initialized, and uses the specified streambuf object for subsequent operations.
The second form is used to associate the ostream object with the streambuf object currently associated with the ostrm parameter. The ostream object is initialized and will use the ostrm 's streambuf object for subsequent operations. The ostrm object continues to use the streambuf object.

Results:

Both forms of the operator =() public member function return a reference to the ostream object that's the target of the assignment.

For the first form, if the sb parameter is NULL, ios::badbit is set in the error state in the inherited ios object.
For the second form, if there's no streambuf object currently associated with the ostrm parameter, ios::badbit is set in the error state in the inherited ios object.

ostream::opfx()

a prefix function that's executed before writing

Synopsis:

#include <iostream.h>
public:
int ostream::opfx();

Semantics:

If opfx() public member function is a prefix function executed before each of the formatted and unformatted output operations. If any bits are set in ios::iostate, the opfx() public member function immediately returns zero, indicating that the prefix function failed. Failure in the prefix function causes the output operation to fail.

If the ostream object is tied to another ostream object, the other ostream object is flushed.

Results:

The opfx() public member function returns a non-zero value on success, otherwise zero is returned.

ostream::osfx()

a suffix function that's executed after writing

Synopsis:

#include <iostream.h>
public:
void ostream::osfx();

Semantics:

The osfx() public member function is a suffix function executed at the end of each of the formatted and unformatted output operations.

If the ios::unitbuf bit is set in ios::fmtflags, the flush() member function is called. If the ios::stdio bit is set in ios::fmtflags, the C library fflush function is invoked on the stdout and stderr file streams.

ostream::ostream()

create a ostream object

Synopsis:

#include <iostream.h>
protected:
ostream::ostream();

public:
ostream::ostream( ostream const &ostrm );
ostream::ostream( streambuf *sb );

Semantics:

There are three forms of the ostream constructor:

The first form is a protected member function that creates an ostream object without an attached streambuf object.
This form of the protected ostream constructor is only used implicitly by the compiler when it generates a constructor for a derived class.
The second form is a public member function. It creates an ostream object associated with the streambuf object currently associated with the ostrm parameter. The ostream object is initialized, and uses the ostrm's streambuf object for subsequent operations. The ostrm object continues to use the streambuf object.
The third form is also a public member function. It creates an ostream object with an associated streambuf object specified by the sb parameter.
This function is likely to be used for the creation of an ostream object that's associated with the same streambuf object as another ostream object.

Results:

All three forms of the ostream constructor create an initialized ostream object:

For the first (protected) form, ios::badbit is set in the error state in the inherited ios object.
For the second (public) form, if there's no streambuf object currently associated with the ostrm parameter, ios::badbit is set in the error state in the inherited ios object.
For the third (public) form, if the sb parameter is NULL, ios::badbit is set in the error state in the inherited ios object.

ostream::~ostream()

destroy a ostream object

Synopsis:

#include <iostream.h>
public:
virtual ostream::~ostream();

Semantics:

The public virtual ostream destructor doesn't do anything explicit. The ios destructor is called for that portion of the ostream object. The call to the public virtual ostream destructor is inserted implicitly by the compiler at the point where the ostream object goes out of scope.

Results:

The ostream object is destroyed.

ostream::put()

write a character to the ostream object

Synopsis:

#include <iostream.h>
public:
ostream &ostream::put(          char ch );
ostream &ostream::put(   signed char ch );
ostream &ostream::put( unsigned char ch );

Semantics:

The put() public member function writes the ch character to the ostream object.

Results:

The put() public member function returns a reference to the ostream object. If an error occurs, ios::failbit is set in the error state in the inherited ios object.

ostream::seekp()

position the ostream object

Synopsis:

#include <iostream.h>
public:
ostream &ostream::seekp( streampos pos );
ostream &ostream::seekp( streamoff offset, 
                             ios::seekdir dir );

Semantics:

There are two forms of the seekp() public member function:

The first positions the ostream object to the position specified by the pos parameter so that the next output operation commences from that position.
The pos value is an absolute position within the stream. It may be obtained via a call to the tellp member function.
The second form positions the ostream object to the specified position so that the next output operation commences from that position.
The dir parameter may be ios::beg, ios::cur, or ios::end and is interpreted in conjunction with the offset parameter as follows:

ios::beg
the offset is relative to the start, and should be a positive value
ios::cur
the offset is relative to the current position, and may be positive (seek towards end) or negative (seek towards start)
ios::end
the offset is relative to the end, and should be a negative value.

If the dir parameter has any other value, or the offset parameter doesn't have an appropriate sign, the seekp() public member function fails.

Results:

Both forms of the seekp() public member function return a reference to the ostream object. If the seek operation fails, ios::failbit is set in the error state in the inherited ios object.

ostream::tellp()

return the position at which the next character will be written

Synopsis:

#include <iostream.h>
public:
streampos ostream::tellp();

Semantics:

The tellp() public member function returns the position in the ostream object at which the next character will be written. The first character in an ostream object is at offset zero.

Results:

The tellp() public member function returns the position in the ostream object at which the next character will be written.

ostream::write()

perform an unformatted write

Synopsis:

#include <iostream.h>
public:
ostream &ostream::write( char const *buf,
                             int len );
ostream &ostream::write( signed char const *buf,
                             int len );
ostream &ostream::write( unsigned char const *buf,
                             int len );

Semantics:

The write() public member function performs an unformatted write of the characters specified by the buf and len parameters into the ostream object.

Results:

These member functions return a reference to the ostream object. If an error occurs, ios::failbit is set in the error state in the inherited ios object.

`ostrstream` Class

Declared:

strstrea.h

Derived from:

strstreambase, ostream

The ostrstream class is used to create and write to string stream objects.

The ostrstream class provides little of its own functionality. Derived from the strstreambase and ostream classes, its constructors and destructor provide simplified access to the appropriate equivalents in those base classes. The member functions provide specialized access to the string stream object.

Of the available I/O stream classes, creating an ostrstream object is the preferred method of performing write operations to a string stream.

Public Member Functions

The following member functions are declared in the public interface:

ostrstream();
ostrstream(      char *, int, ios::openmode = ios::out );
ostrstream(   signed char *, int, ios::openmode = ios::out );
ostrstream( unsigned char *, int, ios::openmode = ios::out );
~ostrstream();
int pcount() const;
char *str();

ostrstream::ostrstream()

create a ostrstream object

Synopsis:

#include <strstrea.h>
public:
ostrstream::ostrstream();

ostrstream::ostrstream( char *str,
              int len,
              ios::openmode mode = ios::out );
ostrstream::ostrstream( signed char *str,
              int len,
              ios::openmode mode = ios::out );
ostrstream::ostrstream( unsigned char *str,
              int len,
              ios::openmode mode = ios::out );

Semantics:

There are four forms of the public ostrstream constructor:

The first creates an empty ostrstream object. Dynamic allocation is used. The inherited stream member functions can be used to access the ostrstream object.
The other three forms create an initialized ostrstream object. Dynamic allocation isn't used. The buffer is specified by the str and len parameters. If the ios::append or ios::atend bits are set in the mode parameter, the str parameter is assumed to contain a C string terminated by a null character, and writing commences at the null character. Otherwise, writing commences at str.

Results:

The first form of the public ostrstream constructor creates an initialized, empty ostrstream object.
The other three forms create an initialized ostrstream object.

ostrstream::~ostrstream()

destroy a ostrstream object

Synopsis:

#include <strstrea.h>
public:
ostrstream::~ostrstream();

Semantics:

The public ostrstream destructor doesn't do anything explicit. The call to it is inserted implicitly by the compiler at the point where the ostrstream object goes out of scope.

Results:

The ostrstream object is destroyed.

ostrstream::pcount()

count the characters that have been written

Synopsis:

#include <strstrea.h>
public:
int ostrstream::pcount() const;

Semantics:

The pcount() public member function computes the number of characters that have been written to the ostrstream object. This value is particularly useful if the ostrstream object doesn't contain a C string (terminated by a null character), so that the number of characters can't be determined with the C library strlen() function.

If the ostrstream object was created by appending to a C string in a static buffer, the length of the original string is included in the character count.

Results:

The pcount() public member function returns the number of characters contained in the ostrstream object.

ostrstream::str()

return a pointer to the buffer used by the ostrstream object

Synopsis:

#include <strstrea.h>
public:
char *ostrstream::str();

Semantics:

The str() public member function creates a pointer to the buffer being used by the ostrstream object. If the ostrstream object was created without dynamic allocation (static mode), the pointer is the same as the buffer pointer passed in the constructor.

For ostrstream objects using dynamic allocation, the str() public member function makes an implicit call to the strstreambuf::freeze() member function. If nothing has been written to the ostrstream object, the returned pointer is NULL.

The buffer doesn't necessarily end with a null character. If the pointer returned by the str() public member function is to be interpreted as a C string, it's the program's responsibility to ensure that the null character is present.

Results:

The str() public member function returns a pointer to the buffer being used by the ostrstream object.

`stdiobuf` Class

Declared:

stdiobuf.h

Derived from:

streambuf

The stdiobuf class specializes the streambuf class, and is used to implement the standard input/output buffering required for the cin, cout, cerr and clog predefined objects.

The stdiobuf class behaves in a similar way to the filebuf class, but doesn't need to switch between the get area and put area, since no stdiobuf object can be created for both reading and writing. When the get area is empty and a read is done, the underflow() virtual member function reads more characters and fills the get area again. When the put area is full and a write is done, the overflow() virtual member function writes the characters and makes the put area empty again.

C++ programmers who wish to use the standard input/output streams without deriving new objects don't need to explicitly create or use a stdiobuf object.

Public Member Functions

The following member functions are declared in the public interface:

stdiobuf();
stdiobuf( FILE * );
~stdiobuf();
virtual int overflow( int = EOF );
virtual int underflow();
virtual int sync();

stdiobuf::overflow()

deal with the put area when it's full

Synopsis:

#include <stdiobuf.h>
public:
virtual int stdiobuf::overflow( int ch = EOF );

Semantics:

The overflow() public virtual member function provides the output communication to the standard output and standard error devices to which the stdiobuf object is connected. Member functions in the streambuf class call the overflow() public virtual member function for the derived class when the put area is full.

This function performs the following steps:

If no buffer is present, a buffer is allocated with the streambuf::allocate() member function, which might call the doallocate() virtual member function. The put area is then set up. If, after calling streambuf::allocate(), no buffer is present, the stdiobuf object is unbuffered, and ch (if not EOF) is written directly to the file without buffering, and no further action is taken.
If the get area is present, it's flushed with a call to the sync() virtual member function. Note that the get area won't be present if a buffer was set up in step 1.
If ch isn't EOF, it's added to the put area, if possible.
Any characters in the put area are written to the file.
The put area pointers are updated to reflect the new state of the put area. If the write didn't complete, the unwritten portion of the put area is still present. If the put area was full before the write, ch (if not EOF) is placed at the start of the put area. Otherwise, the put area is empty.

Results:

The overflow() public virtual member function returns __NOT_EOF on success, otherwise EOF is returned.

stdiobuf::stdiobuf()

create a stdiobuf object

Synopsis:

#include <stdiobuf.h>
public:
stdiobuf::stdiobuf();
stdiobuf::stdiobuf( FILE *fptr );

Semantics:

There are two forms of the public stdiobuf constructor:

The first creates a stdiobuf object that's initialized but not yet connected to a file.
The second form creates a stdiobuf object that's initialized and connected to a C library FILE stream. Usually, one of stdin, stdout or stderr is specified for the fptr parameter.

Results:

The public stdiobuf constructor creates a stdiobuf object.

stdiobuf::~stdiobuf()

destroy a stdiobuf object

Synopsis:

#include <stdiobuf.h>
public:
stdiobuf::~stdiobuf();

Semantics:

The public stdiobuf destructor doesn't do anything explicit. The streambuf destructor is called for that portion of the stdiobuf object. The call to the public stdiobuf destructor is inserted implicitly by the compiler at the point where the stdiobuf object goes out of scope.

Results:

The stdiobuf object is destroyed.

stdiobuf::sync()

synchronize the stdiobuf object and the associated device

Synopsis:

#include <stdiobuf.h>
public:
virtual int stdiobuf::sync();

Semantics:

The sync() public virtual member function synchronizes the stdiobuf object with the associated device. If the put area contains characters, it's flushed. If the get area contains buffered characters, the sync() public virtual member function fails.

Results:

The sync() public virtual member function returns __NOT_EOF on success, otherwise, EOF is returned.

stdiobuf::underflow()

deal with the get area when it's empty

Synopsis:

#include <stdiobuf.h>
public:
virtual int stdiobuf::underflow();

Semantics:

The underflow() public virtual member function provides the input communication from the standard input device to which the stdiobuf object is connected. Member functions in the streambuf class call the underflow() public virtual member function for the derived class when the get area is empty.

This function performs the following steps:

If no reserve area is present, a buffer is allocated with the streambuf::allocate() member function, which might call the doallocate() virtual member function. If, after calling allocate(), no reserve area is present, the stdiobuf object is unbuffered, and a one-character reserve area (plus putback area) is set up to do unbuffered input. This buffer is embedded in the stdiobuf object. The get area is set up as empty.
The unused part of the get area is used to read characters from the file connected to the stdiobuf object. The get area pointers are then set up to reflect the new get area.

Results:

The underflow() public virtual member function returns the first unread character of the get area, on success, otherwise EOF is returned. Note that the get pointer isn't advanced on success.

`streambuf` Class

Declared:

streambu.h

Derived from:

filebuf, stdiobuf, strstreambuf

The streambuf class is responsible for maintaining the buffer used to create an efficient implementation of the stream classes. Through its pure virtual functions, it's also responsible for the actual communication with the device associated with the stream.

The streambuf class is abstract, due to the presence of pure virtual member functions. Abstract classes may not be instantiated, only inherited. Hence, streambuf objects won't be created by user programs.

Stream objects maintain a pointer to an associated streambuf object, and present the interface that the user deals with most often. Whenever a stream member function wishes to read or write characters, it uses the rdbuf() member function to access the associated streambuf object and its member functions. Through judicious use of inline functions, most reads and writes of characters access the buffer directly without even doing a function call. Whenever the buffer gets filled (writing) or exhausted (reading), these inline functions invoke the function required to rectify the situation so that the proper action can take place.

A streambuf object can be unbuffered, but most often has one buffer that can be used for both input and output operations. The buffer (called the reserve area) is divided into two areas, called the get area and the put area. For a streambuf object being used exclusively to write, the get area is empty or not present. Likewise, a streambuf object being used exclusively for reading has an empty or non-existent put area.

The use of the get area and put area differs among the various classes derived from the streambuf class.

When writing is occurring, the characters are buffered in the put area. If a seek or read operation is done, the put area must be flushed before the next operation, in order to ensure that the characters are written to the proper location in the file.
Similarly, if reading is occurring, characters are buffered in the get area. If a write operation is done, the get area must be flushed and synchronized before the write operation in order to ensure the write occurs at the proper location in the file. If a seek operation is done, the get area doesn't have to be synchronized, but is discarded.
When the get area is empty and a read is done, the underflow() virtual member function reads more characters and fills the get area again.
When the put area is full and a write is done, the overflow() virtual member function writes the characters and makes the put area empty again.

When the get area is empty and a read is done, the underflow() virtual member function reads more characters and fills the get area again.
When the put area is full and a write is done, the overflow() virtual member function writes the characters and makes the put area empty again.

The strstreambuf class differs quite markedly from the filebuf and stdiobuf classes. Since there's no actual source or destination for the characters in strstream objects, the buffer itself takes on that role:

When writing is occurring and the put area is full, the overflow() virtual member function reallocates the buffer to a larger size (if possible), the put area is extended, and the writing continues.
If reading is occurring and the get area is empty, the underflow() virtual member function checks to see if the put area is present and not empty. If so, the get area is extended to overlap the put area.

The reserve area is marked by two pointer values:

The base() member function returns the pointer to the start of the buffer.
The ebuf() member function returns the pointer to the end of the buffer (last character + 1)

The setb() protected member function is used to set both pointers.

Within the reserve area, the get area is marked by three pointer values:

The eback() member function returns a pointer to the start of the get area.
The egptr() member function returns a pointer to the end of the get area (last character + 1).
The gptr() member function returns the get pointer. This is a pointer to the next character to be extracted from the get area. Characters before the get pointer have already been consumed by the program, while characters at and after the get pointer have been read from their source, and are buffered and waiting to be read by the program.

The setg() member function is used to set all three pointer values. If any of these pointers are NULL, there's no get area.

Also within the reserve area, the put area is marked by three pointer values:

The pbase() member function returns a pointer to the start of the put area.
The epptr() member function returns a pointer to the end of the put area (last character + 1 ).
The pptr() member function returns the put pointer. This is a pointer to the next available position into which a character may be stored. Characters before the put pointer are buffered and waiting to be written to their final destination, while character positions at and after the put pointer have yet to be written by the program.

The setp() member function is used to set all three pointer values. If any of these pointers are NULL, there's no put area.

In summary, the reserve area, get area, and put area pointer functions return the following values:

base(): start of the reserve area.
ebuf(): end of the reserve area.
blen(): length of the reserve area.
eback(): start of the get area.
gptr(): the get pointer.
egptr(): end of the get area.
pbase(): start of the put area.
pptr(): the put pointer.
epptr(): end of the put area.

From eback() to gptr() are characters buffered and read. From gptr() to egptr() are characters buffered but not yet read. From pbase() to pptr() are characters buffered and not yet written. From pptr() to epptr() is unused buffer area.

Unbuffered I/O is also possible. If unbuffered, the overflow() virtual member function is used to write single characters directly to their final destination without using the put area. Similarly, the underflow() virtual member function is used to read single characters directly from their source without using the get area.

Protected Member Functions

The following member functions are declared in the protected interface:

streambuf();
streambuf( char *, int );
virtual ~streambuf();
int allocate();
char *base() const;
char *ebuf() const;
int blen() const;
void setb( char *, char *, int );
char *eback() const;
char *gptr() const;
char *egptr() const;
void gbump( streamoff );
void setg( char *, char *, char *);
char *pbase() const;
char *pptr() const;
char *epptr() const;
void pbump( streamoff );
void setp( char *, char *);
int unbuffered( int );
int unbuffered() const;
virtual int doallocate();

Public Member Functions

The following member functions are declared in the public interface:

int in_avail() const;
int out_waiting() const;
int snextc();
int sgetn( char *, int );
int speekc();
int sgetc();
int sgetchar();
int sbumpc();
void stossc();
int sputbackc( char );
int sputc( int );
int sputn( char const *, int );
void dbp();

virtual int do_sgetn( char *, int );
virtual int do_sputn( char const *, int );
virtual int pbackfail( int );
virtual int overflow( int = EOF ) = 0;
virtual int underflow() = 0;
virtual streambuf *setbuf( char *, int );
virtual streampos seekoff( streamoff, ios::seekdir,
                ios::openmode = ios::in|ios::out );
virtual streampos seekpos( streampos,
                ios::openmode = ios::in|ios::out );
virtual int sync();

streambuf::allocate()

manage allocation of the reserve area

Synopsis:

#include <streambu.h>
protected:
int streambuf::allocate();

Semantics:

The allocate() protected member function works in tandem with the doallocate() protected virtual member function to manage allocation of the streambuf object reserve area.

Classes derived from the streambuf class should call the allocate() protected member function, rather than the doallocate() protected virtual member function.

The allocate() protected member function determines whether or not the streambuf object is allowed to allocate a buffer for use as the reserve area. If a reserve area already exists or if the streambuf object unbuffering state is non-zero, the allocate() protected member function fails. Otherwise, it calls the doallocate() protected virtual member function.

Results:

The allocate() protected member function returns __NOT_EOF on success, otherwise EOF is returned.

streambuf::base()

return a pointer to the start of the reserve area

Synopsis:

#include <streambu.h>
protected:
char *streambuf::base() const;

Semantics:

The base() protected member function returns a pointer to the start of the reserve area that the streambuf object is using.

Results:

The base() protected member function returns a pointer to the start of the reserve area that the streambuf object is using. If the streambuf object currently doesn't have a reserve area, NULL is returned.

streambuf::blen()

return the length of the reserve area

Synopsis:

#include <streambu.h>
protected:
int streambuf::blen() const;

Semantics:

The blen() protected member function reports the length of the reserve area that the streambuf object is using.

Results:

The blen() protected member function returns the length of the reserve area that the streambuf object is using. If the streambuf object currently doesn't have a reserve area, zero is returned.

streambuf::dbp()

dump information about the stream buffer

Synopsis:

#include <streambu.h>
public:
void streambuf::dbp();

Semantics:

The dbp() public member function dumps information about the streambuf object directly to stdout, and is used for debugging classes derived from the streambuf class.

The following is an example of what the dbp() public member function dumps:

STREAMBUF Debug Info:
this  = 00030679, unbuffered = 0, delete_reserve = 1
base  = 00070010, ebuf = 00070094
eback = 00000000, gptr = 00000000, egptr = 00000000
pbase = 00070010, pptr = 00070010, epptr = 00070094

streambuf::do_sgetn()

transfer characters from the get area

Synopsis:

#include <streambu.h>
public:
virtual int do_sgetn( char *buf, int len );

Semantics:

The do_sgetn() public virtual member function works in tandem with the sgetn member function to transfer len characters from the get area into buf.

Classes derived from the streambuf class should call the sgetn member function, rather than the do_sgetn() public virtual member function.

Derived Implementation Protocol:

Classes derived from the streambuf class that implement the do_sgetn() public virtual member function should support copying up to len characters from the source through the get area and into buf.

Default Implementation:

The default do_sgetn() public virtual member function provided with the streambuf class calls the underflow() virtual member function to fetch more characters, and then copies the characters from the get area into buf.

Results:

The do_sgetn() public virtual member function returns the number of characters successfully transferred.

streambuf::do_sputn()

transfer characters from the put area

Synopsis:

#include <streambu.h>
public:
virtual int do_sputn( char const *buf, int len );

Semantics:

The do_sputn() public virtual member function works in tandem with the sputn member function to transfer len characters from buf to the end of the put area and advances the put pointer.

Classes derived from the streambuf class should call the sputn member function, rather than the do_sputn() public virtual member function.

Derived Implementation Protocol:

Classes derived from the streambuf class that implement the do_sputn() public virtual member function should support copying up to len characters from buf through the put area and out to the destination device.

Default Implementation:

The default do_sputn() public virtual member function provided with the streambuf class calls the overflow() virtual member function to flush the put area, and then copies the rest of the characters from buf into the put area.

Results:

The do_sputn() public virtual member function returns the number of characters successfully written. If an error occurs, this number might be less than len.

streambuf::doallocate()

manage allocation of the reserve area

Synopsis:

#include <streambu.h>
protected:
virtual int streambuf::doallocate();

Semantics:

The doallocate() protected virtual member function manages allocation of the streambuf object's reserve area in tandem with the allocate() protected member function.

Classes derived from the streambuf class should call the allocate() protected member function rather than the doallocate() protected virtual member function.

The doallocate() protected virtual member function does the actual memory allocation, and can be defined for each class derived from the streambuf class.

Derived Implementation Protocol:

Classes derived from the streambuf class should implement the doallocate() protected virtual member function such that it does the following:

attempts to allocate an area of memory,
calls the setb() protected member function to initialize the reserve area pointers,
performs any class specific operations required.

Default Implementation:

The default doallocate() protected virtual member function provided with the streambuf class attempts to allocate a buffer area with the operator new() intrinsic function. It then calls the setb() protected member function to set up the pointers to the reserve area.

Results:

The doallocate() protected virtual member function returns __NOT_EOF on success, otherwise EOF is returned.

streambuf::eback()

return a pointer to the start of the get area

Synopsis:

#include <streambu.h>
protected:
char *streambuf::eback() const;

Semantics:

The eback() protected member function returns a pointer to the start of the get area within the reserve area used by the streambuf object.

Results:

The eback() protected member function returns a pointer to the start of the get area. If the streambuf object currently doesn't have a get area, NULL is returned.

streambuf::ebuf()

return a pointer to the end of the reserve area

Synopsis:

#include <streambu.h>
protected:
char *streambuf::ebuf() const;

Semantics:

The ebuf() protected member function returns a pointer to the end of the reserve area that the streambuf object is using. The character pointed at is actually the first character past the end of the reserve area.

Results:

The ebuf() protected member function returns a pointer to the end of the reserve area. If the streambuf object currently doesn't have a reserve area, NULL is returned.

streambuf::egptr()

return a pointer to the end of the get area

Synopsis:

#include <streambu.h>
protected:
char *streambuf::egptr() const;

Semantics:

The egptr() protected member function returns a pointer to the end of the get area within the reserve area used by the streambuf object. The character pointed at is actually the first character past the end of the get area.

Results:

The egptr() protected member function returns a pointer to the end of the get area. If the streambuf object currently doesn't have a get area, NULL is returned.

streambuf::epptr()

return a pointer to the end of the put area

Synopsis:

#include <streambu.h>
protected:
char *streambuf::epptr() const;

Semantics:

The epptr() protected member function returns a pointer to the end of the put area within the reserve area used by the streambuf object. The character pointed at is actually the first character past the end of the put area.

Results:

The epptr() protected member function returns a pointer to the end of the put area. If the streambuf object currently doesn't have a put area, NULL is returned.

streambuf::gbump()

increment the get pointer

Synopsis:

#include <streambu.h>
protected:
void streambuf::gbump( streamoff offset );

Semantics:

The gbump() protected member function increments the get pointer by the specified offset, without regard for the boundaries of the get area. The offset parameter may be positive or negative.

Results:

The gbump() protected member function returns nothing.

streambuf::gptr()

return a pointer to the next available character in the get area

Synopsis:

#include <streambu.h>
protected:
char *streambuf::gptr() const;

Semantics:

The gptr() protected member function returns a pointer to the next available character in the get area within the reserve area used by the streambuf object. This pointer is called the get pointer.

If the get pointer points beyond the end of the get area, all characters in the get area have been read by the program, and a subsequent read causes the underflow() virtual member function to be called to fetch more characters from the source to which the streambuf object is attached.

Results:

The gptr() protected member function returns a pointer to the next available character in the get area. If the streambuf object currently doesn't have a get area, NULL is returned.

streambuf::in_avail()

count the buffered characters not yet read by the program

Synopsis:

#include <streambu.h>
public:
int streambuf::in_avail() const;

Semantics:

The in_avail() public member function computes the number of input characters buffered in the get area that haven't yet been read by the program. These characters can be read with a guarantee that no errors will occur.

Results:

The in_avail() public member function returns the number of buffered input characters.

streambuf::out_waiting()

count the buffered characters not yet written to the device

Synopsis:

#include <streambu.h>
public:
int streambuf::out_waiting() const;

Semantics:

The out_waiting() public member function computes the number of characters that have been buffered in the put area and not yet been written to the output device.

Results:

The out_waiting() public member function returns the number of buffered output characters.

streambuf::overflow()

flush the put area when it's full

Synopsis:

#include <streambu.h>
public:
virtual int streambuf::overflow( 
   int ch = EOF ) = 0;

Semantics:

The overflow() public virtual member function is used to flush the put area when it's full.

Derived Implementation Protocol:

Classes derived from the streambuf class should implement the overflow() public virtual member function so that it performs the following:

if no reserve area is present and the streambuf object isn't unbuffered, allocate a reserve area using the allocate() member function, and set up the reserve area pointers using the setb() protected member function,
flush any other uses of the reserve area,
write any characters in the put area to the streambuf object's destination,
set up the put area pointers to reflect the characters that were written,
return __NOT_EOF on success, otherwise return EOF.

Default Implementation:

There's no default streambuf class implementation of the overflow() public virtual member function. The overflow() public virtual member function must be defined for all classes derived from the streambuf class.

Results:

The overflow() public virtual member function returns __NOT_EOF on success, otherwise EOF is returned.

streambuf::pbackfail()

handle a failed attempt to put a character back

Synopsis:

#include <streambu.h>
public:
virtual int streambuf::pbackfail( int ch );

Semantics:

The pbackfail() public virtual member function is called by the sputbackc() member function when the get pointer is at the beginning of the get area, and so there's no place to put the ch parameter.

Derived Implementation Protocol:

Classes derived from the streambuf class should implement the pbackfail() public virtual member function such that it attempts to put ch back into the source of the stream.

Default Implementation:

The default streambuf class implementation of the pbackfail() public virtual member function is to return EOF.

Results:

If the pbackfail() public virtual member function succeeds, it returns ch. Otherwise, it returns EOF.

streambuf::pbase()

return a pointer to the start of the put area

Synopsis:

#include <streambu.h>
protected:
char *streambuf::pbase() const;

Semantics:

The pbase() protected member function returns a pointer to the start of the put area within the reserve area used by the streambuf object.

Results:

The pbase() protected member function returns a pointer to the start of the put area. If the streambuf object currently doesn't have a put area, NULL is returned.

streambuf::pbump()

increment the put pointer

Synopsis:

#include <streambu.h>
protected:
void streambuf::pbump( streamoff offset );

Semantics:

The pbump() protected member function increments the put pointer by the specified offset, without regard for the boundaries of the put area. The offset parameter may be positive or negative.

Results:

The pbump() protected member function returns nothing.

streambuf::pptr()

return a pointer to the next available space in the put area

Synopsis:

#include <streambu.h>
protected:
char *streambuf::pptr() const;

Semantics:

The pptr() protected member function returns a pointer to the next available space in the put area within the reserve area used by the streambuf object. This pointer is called the put pointer.

If the put pointer points beyond the end of the put area, the put area is full, and a subsequent write causes the overflow() virtual member function to be called to empty the put area to the device to which the streambuf object is attached.

Results:

The pptr() protected member function returns a pointer to the next available space in the put area. If the streambuf object currently doesn't have a put area, NULL is returned.

streambuf::sbumpc()

extract the next available character from the get area

Synopsis:

#include <streambu.h>
public:
int streambuf::sbumpc();

Semantics:

The sbumpc() public member function extracts the next available character from the get area, and advances the get pointer. If no character is available, it calls the underflow() virtual member function to fetch more characters from the source into the get area.

Due to the sbumpc() member functions's awkward name, the sgetchar() member function was added to take its place in the WATCOM implementation.

Results:

The sbumpc() public member function returns the next available character in the get area. If no character is available, EOF is returned.

streambuf::seekoff()

move to a relative position in the stream buffer

Synopsis:

#include <streambu.h>
public:
virtual streampos streambuf::seekoff( 
                        streamoff offset,
                        ios::seekdir dir,
                        ios::openmode mode );

Semantics:

The seekoff() public virtual member function is used for positioning to a relative location within the streambuf object, and hence within the device that's connected to the streambuf object. The offset and dir parameters specify the relative change in position. The mode parameter controls whether the get pointer and/or the put pointer are repositioned.

Derived Implementation Protocol:

Classes derived from the streambuf class should implement the seekoff() virtual member function so that it uses its parameters in the way described below.

The mode parameter may be ios::in, ios::out, or ios::in|ios::out, and should be interpreted as follows, provided the interpretation is meaningful:

ios::in: the get pointer should be moved.
ios::out: the put pointer should be moved.
ios::in|ios::out: both the get pointer and the put pointer should be moved.

If mode has any other value, the seekoff() public virtual member function fails.

The dir parameter may be ios::beg, ios::cur, or ios::end, and is interpreted in conjunction with the offset parameter as follows:

ios::beg: the offset is relative to the start, and should be a positive value.
ios::cur: the offset is relative to the current position, and may be positive (seek towards end) or negative (seek towards start).
ios::end: the offset is relative to the end, and should be a negative value.

If the dir parameter has any other value, or the offset parameter doesn't have an appropriate sign, the seekoff() public virtual member function fails.

Default Implementation:

The default implementation of the seekoff() public virtual member function provided by the streambuf class returns EOF.

Results:

The seekoff() public virtual member function returns the new position in the stream on success, otherwise EOF is returned.

streambuf::seekpos()

move to an absolute position in the stream buffer

Synopsis:

#include <streambu.h>
public:
virtual streampos streambuf::seekpos( 
    streampos pos,
    ios::openmode mode = ios::in|ios::out );

Semantics:

The seekpos() public virtual member function is used for positioning to an absolute location within the streambuf object, and hence within the device that's connected to the streambuf object. The pos parameter specifies the absolute position. The mode parameter controls whether the get pointer and/or the put pointer are repositioned.

Derived Implementation Protocol:

Classes derived from the streambuf class should implement the seekpos() public virtual member function so that it uses its parameters in the following way.

The mode parameter may be ios::in, ios::out, or ios::in|ios::out, and should be interpreted as follows, provided the interpretation is meaningful:

ios::in: the get pointer should be moved.
ios::out: the put pointer should be moved.
ios::in|ios::out: both the get pointer and the put pointer should be moved.

If mode has any other value, the seekpos() public virtual member function fails.

In general the seekpos() public virtual member function is equivalent to calling the seekoff() virtual member function with the offset set to pos, the direction set to ios::beg, and the mode set to mode.

Default Implementation:

The default implementation of the seekpos() public virtual member function provided by the streambuf class calls the seekoff() virtual member function with the offset set to pos, the direction set to ios::beg, and the mode set to mode.

Results:

The seekpos() public virtual member function returns the new position in the stream on success, otherwise EOF is returned.

streambuf::setb()

set the pointers to the reserve area

Synopsis:

#include <streambu.h>
protected:
void streambuf::setb( char *base, char *ebuf, 
                      int autodel );

Semantics:

The setb() protected member function is used to set the pointers to the reserve area that the streambuf object is using.

The base parameter is a pointer to the start of the reserve area, and corresponds to the value that the base() member function returns.

The ebuf parameter is a pointer to the end of the reserve area, and corresponds to the value that the ebuf() member function returns.

The autodel parameter indicates whether or not the streambuf object can free the reserve area when the streambuf object is destroyed or when a new reserve area is set up in a subsequent call to the setb() protected member function. If the autodel parameter is non-zero, the streambuf object can delete the reserve area, using the operator delete() intrinsic function. A zero value indicates that the buffer will be deleted elsewhere.

If either of the base or ebuf parameters is NULL, or if ebuf <= base, the streambuf object doesn't have a buffer, and input/output operations are unbuffered, unless another buffer is set up.

The setb() protected member function is used to set the reserve area pointers, while the setbuf() protected member function is used to offer a buffer to the streambuf object.

streambuf::setbuf()

offer a buffer to the streambuf object

Synopsis:

#include <streambu.h>
public:
virtual streambuf *streambuf::setbuf( char *buf, 
                                      int len );

Semantics:

The setbuf() public virtual member function is used to offer a buffer specified by the buf and len parameters to the streambuf object for use as its reserve area.

The setbuf() public virtual member function is used to offer a buffer, while the setb() protected member function is used to set the reserve area pointers once a buffer has been accepted.

Derived Implementation Protocol:

Classes derived from the streambuf class may implement the setbuf() public virtual member function if the default behavior isn't suitable.

Derived classes that provide their own implementations of the setbuf() public virtual member function may accept or reject the offered buffer. Often, if a buffer is already allocated, the offered buffer is rejected, as it might be difficult to transfer the information from the current buffer.

Default Implementation:

The default setbuf() public virtual member function provided by the streambuf class rejects the buffer if one's already present.

If no buffer is present and either buf is NULL or len is zero, the offer is accepted and the streambuf object is unbuffered.

Otherwise, no buffer is present and one is specified. If len is less than five characters the buffer is too small and it's rejected. Otherwise, the buffer is accepted.

Results:

The setbuf() public virtual member function returns the address of the streambuf object if the offered buffer is accepted, otherwise NULL is returned.

streambuf::setg()

set the three get area pointers

Synopsis:

#include <streambu.h>
protected:
void streambuf::setg( char *eback, char *gptr, 
                      char *egptr );

Semantics:

The setg() protected member function is used to set the three get area pointers:

The eback parameter is a pointer to the start of the get area, and corresponds to the value that the eback() member function returns.
The gptr parameter is a pointer to the first available character in the get area, that is, the get pointer, and usually is greater than the eback() parameter, in order to accommodate a putback area. The gptr parameter corresponds to the value that the gptr() member function returns.
The egptr parameter is a pointer to the end of the get area and corresponds to the value that the egptr() member function returns.

If any of the three parameters are NULL, there's no get area.

streambuf::setp()

set the three put area pointers

Synopsis:

#include <streambu.h>
protected:
void streambuf::setp( char *pbase, char *epptr );

Semantics:

The setp() protected member function is used to set the three put area pointers:

The pbase parameter is a pointer to the start of the put area, and corresponds to the value that the pbase() member function returns.
The epptr parameter is a pointer to the end of the put area, and corresponds to the value that the epptr() member function returns.
The put pointer is set to the pbase parameter value, and corresponds to the value that the pptr() member function returns.

If either parameter is NULL, there's no put area.

streambuf::sgetc()

return the next available character in the get area

Synopsis:

#include <streambu.h>
public:
int streambuf::sgetc();

Semantics:

The sgetc() public member function returns the next available character in the get area. The get pointer isn't advanced. If the get area is empty, the underflow() virtual member function is called to fetch more characters from the source into the get area.

Due to the sgetc member function's confusing name (the C library getc function does advance the pointer), the speekc member function was added to take its place in the WATCOM implementation.

Results:

The sgetc() public member function returns the next available character in the get area. If no character is available, EOF is returned.

streambuf::sgetchar()

get the next available character in the get area

Synopsis:

#include <streambu.h>
public:
int streambuf::sgetchar();

Semantics:

The sgetchar() public member function extracts the next available character from the get area, and advances the get pointer. If no character is available, it calls the underflow() virtual member function to fetch more characters from the source into the get area.

Due to the sbumpc() member functions's awkward name, the sgetchar() member function was added to take its place in the WATCOM implementation.

Results:

The sgetchar() public member function returns the next available character in the get area. If no character is available, EOF is returned.

streambuf::sgetn()

get a number of characters from the get area

Synopsis:

#include <streambu.h>
public:
int streambuf::sgetn( char *buf, int len );

Semantics:

The sgetn() public member function transfers up to len characters from the get area into buf. If there aren't enough characters in the get area, the do_sgetn() virtual member function is called to fetch more.

Classes derived from the streambuf class should call the sgetn() public member function, rather than the do_sgetn() virtual member function.

Results:

The sgetn() public member function returns the number of characters transferred from the get area into buf.

streambuf::snextc()

advance the get pointer, and return the character

Synopsis:

#include <streambu.h>
public:
int streambuf::snextc();

Semantics:

The snextc() public member function advances the get pointer, and then returns the character following the get pointer. The get pointer is left pointing at the returned character.

If the get pointer can't be advanced, the underflow() virtual member function is called to fetch more characters from the source into the get area.

Results:

The snextc() public member function advances the get pointer and returns the next available character in the get area. If there's no next available character, EOF is returned.

streambuf::speekc()

return the next character, without advancing the get pointer

Synopsis:

#include <streambu.h>
public:
int streambuf::speekc();

Semantics:

The speekc() public member function returns the next available character in the get area. The get pointer isn't advanced. If the get area is empty, the underflow() virtual member function is called to fetch more characters from the source into the get area.

Due to the sgetc member function's confusing name (the C library getc function does advance the pointer), the speekc member function was added to take its place in the WATCOM implementation.

Results:

The speekc() public member function returns the next available character in the get area. If no character is available, EOF is returned.

streambuf::sputbackc()

put a character back into the get area

Synopsis:

#include <streambu.h>
public:
int streambuf::sputbackc( char ch );

Semantics:

The sputbackc() public member function is used to put a character back into the get area. The ch character specified must be the same as the character before the get pointer, otherwise the behavior is undefined. The get pointer is backed up by one position. At least four characters may be put back without any intervening reads.

Results:

The sputbackc() public member function returns ch on success, otherwise EOF is returned.

streambuf::sputc()

add a character to the end of the put area, advancing the put pointer

Synopsis:

#include <streambu.h>
public:
int streambuf::sputc( int ch );

Semantics:

The sputc() public member function adds the character ch to the end of the put area and advances the put pointer. If the put area is full before the character is added, the overflow() virtual member function is called to empty the put area and write the character.

Results:

The sputc() public member function returns ch on success, otherwise EOF is returned.

streambuf::sputn()

add a number of characters to the put area

Synopsis:

#include <streambu.h>
public:
int streambuf::sputn( char const *buf, int len );

Semantics:

The sputn() public member function transfers up to len characters from buf to the end of the put area and advance the put pointer. If the put area is full or becomes full, and more characters are to be written, the do_sputn() virtual member function is called to empty the put area and finish writing the characters.

Classes derived from the streambuf class should call the sputn() public member function, rather than the do_sputn() virtual member function.

Results:

The sputn() public member function returns the number of characters successfully written. If an error occurs, this number might be less than len.

streambuf::stossc()

advance the get pointer without returning a character

Synopsis:

#include <streambu.h>
public:
void streambuf::stossc();

Semantics:

The stossc() public member function advances the get pointer by one without returning a character. If the get area is empty, the underflow() virtual member function is called to fetch more characters, and then the get pointer is advanced.

streambuf::streambuf()

create a streambuf object

Synopsis:

#include <streambu.h>
protected:
streambuf::streambuf();
streambuf::streambuf( char *buf, int len );

Semantics:

There are two forms of the protected streambuf constructor:

The first creates an empty streambuf object with all fields initialized to zero. No reserve area is yet allocated, but the streambuf object is buffered unless a subsequent call to the setbuf() or unbuffered member functions dictates otherwise.
The second form creates an empty streambuf object with all fields initialized to zero. The buf and len parameters are passed to the setbuf() member function, which sets up the buffer (if specified), or makes the streambuf object unbuffered (if the buf parameter is NULL or the len parameter isn't positive).

Results:

The first form of the protected streambuf constructor creates an initialized streambuf object with no associated reserve area.
The second form creates an initialized streambuf object with an associated reserve area.

streambuf::~streambuf()

destroy a streambuf object

Synopsis:

#include <streambu.h>
protected:
virtual streambuf::~streambuf();

Semantics:

The streambuf object is destroyed. If the buffer was allocated by the streambuf object, it's freed. Otherwise, the buffer isn't freed, and must be freed by the user of the streambuf object. The call to the protected streambuf destructor is inserted implicitly by the compiler at the point where the streambuf object goes out of scope.

Results:

The streambuf object is destroyed.

streambuf::sync()

synchronize the stream buffer and the associated device

Synopsis:

#include <streambu.h>
public:
virtual int streambuf::sync();

Semantics:

The sync() public virtual member function is used to synchronize the streambuf object's get area and put area with the associated device.

Derived Implementation Protocol:

Classes derived from the streambuf class should implement the sync() public virtual member function such that it attempts to perform the following:

flush the put area,
discard the contents of the get area, and reposition the stream device so that the discarded characters may be read again.

Default Implementation:

The default implementation of the sync() public virtual member function provided by the streambuf class takes no action. It succeeds if the get area and the put area are empty, otherwise it fails.

Results:

The sync() public virtual member function returns __NOT_EOF on success, otherwise it returns EOF.

streambuf::unbuffered()

query and/or set the unbuffering state of the object

Synopsis:

#include <streambu.h>
protected:
int ios::unbuffered() const;
int ios::unbuffered( int unbuf );

Semantics:

The unbuffered() protected member function is used to query and/or set the unbuffering state of the streambuf object. A non-zero unbuffered state indicates that the streambuf object is unbuffered. An unbuffered state of zero indicates that the streambuf object is buffered.

The first form of the unbuffered() protected member function is used to query the current unbuffering state.

The second form of the function is used to set the unbuffering state to unbuf.

The unbuffering state only affects the allocate() protected member function, which does nothing if the unbuffering state is non-zero. Setting the unbuffering state to a non-zero value doesn't mean that future I/O operations will be unbuffered.

To determine if current I/O operations are unbuffered, use the base() protected member function. A return value of NULL from this function indicates that unbuffered I/O operations will be used.

Results:

The unbuffered() protected member function returns the previous unbuffered state.

streambuf::underflow()

fill the get area when it's empty

Synopsis:

#include <streambu.h>
public:
virtual int streambuf::underflow() = 0;

Semantics:

The underflow() public virtual member function is used to fill the get area when it's empty.

Derived Implementation Protocol:

Classes derived from the streambuf class should implement the underflow() public virtual member function so that it performs the following:

if no reserve area is present and the streambuf object is buffered, allocate the reserve area using the allocate() member function and set up the reserve area pointers, using the setb() protected member function,
flush any other uses of the reserve area,
read some characters from the streambuf object's source into the get area,
set up the get area pointers to reflect the characters that were read,
return the first character of the get area, or EOF if no characters could be read.

Default Implementation:

There's no default streambuf class implementation of the underflow() public virtual member function. The underflow() public virtual member function must be defined for all classes derived from the streambuf class.

Results:

The underflow() public virtual member function returns the first character read into the get area, or EOF if no characters could be read.

`strstream` Class

Declared:

strstrea.h

Derived from:

strstreambase, iostream

The strstream class is used to create and write to string stream objects.

The strstream class provides little of its own functionality. Derived from the strstreambase and iostream classes, its constructors and destructor provide simplified access to the appropriate equivalents in those base classes. The member functions provide specialized access to the string stream object.

Of the available I/O stream classes, creating a strstream object is the preferred method of performing read and write operations on a string stream.

Public Member Functions

The following member functions are declared in the public interface:

strstream();
strstream( char *,
        int,
        ios::openmode = ios::in|ios::out );
strstream( signed char *,
        int,
        ios::openmode = ios::in|ios::out );
strstream( unsigned char *,
        int,
        ios::openmode = ios::in|ios::out );
~strstream();
char *str();

strstream::str()

return a pointer to the buffer used by the strstream object

Synopsis:

#include <strstrea.h>
public:
char *strstream::str();

Semantics:

The str() public member function creates a pointer to the buffer being used by the strstream object. If the strstream object was created without dynamic allocation (static mode), the pointer is the same as the buffer pointer passed in the constructor.

For strstream objects using dynamic allocation, the str() public member function makes an implicit call to the strstreambuf::freeze() member function. If nothing has been written to the strstream object, the returned pointer will be NULL.

Results:

The str() public member function returns a pointer to the buffer being used by the strstream object.

strstream::strstream()

create a strstream object, with dynamic allocation

Synopsis:

#include <strstrea.h>
public:
strstream::strstream();

strstream::strstream( char *str,
            int len,
            ios::openmode mode );
strstream::strstream( signed char *str,
            int len,
            ios::openmode mode );
strstream::strstream( unsigned char *str,
            int len,
            ios::openmode mode );

Semantics:

There are four forms of the public strstream constructor:

The first creates an empty strstream object. Dynamic allocation is used. The inherited stream member functions can be used to access the strstream object.

The get pointer and put pointer aren't necessarily pointing at the same location, so moving one pointer (for example, by doing a write) doesn't affect the location of the other pointer.

The other three forms create an initialized strstream object. Dynamic allocation isn't used. The buffer is specified by the str and len parameters. If the ios::append or ios::atend bits are set in the mode parameter, the str parameter is assumed to contain a C string terminated by a null character, and writing commences at the null character. Otherwise, writing commences at str. Reading commences at str.

Results:

The first form of the public strstream constructor creates an initialized, empty strstream object.
The other three forms create an initialized strstream object.

strstream::~strstream()

destroy a strstream object

Synopsis:

#include <strstrea.h>
public:
strstream::~strstream();

Semantics:

The public strstream destructor doesn't do anything explicit. The call to it is inserted implicitly by the compiler at the point where the strstream object goes out of scope.

Results:

The strstream object is destroyed.

`strstreambase` Class

Declared:

strstrea.h

Derived from:

ios

Derived by:

istrstream, ostrstream, strstream

The strstreambase class is a base class that provides common functionality for the three string stream-based classes, istrstream, ostrstream and strstream. The strstreambase class is derived from the ios class, which provides the stream state information. The strstreambase class provides constructors for string stream objects and one member function.

Protected Member Functions

The following member functions are declared in the protected interface:

strstreambase();
strstreambase( char *, int, char * = 0 );
~strstreambase();

Public Member Functions

The following member function is declared in the public interface:

strstreambuf *rdbuf() const;

strstreambase::rdbuf()

return a pointer to the strstreambuf object

Synopsis:

#include <strstrea.h>
public:
strstreambuf *strstreambase::rdbuf() const;

Semantics:

The rdbuf() public member function creates a pointer to the strstreambuf associated with the strstreambase object. Since the strstreambuf object is embedded within the strstreambase object, this function never returns NULL.

Results:

The rdbuf() public member function returns a pointer to the strstreambuf associated with the strstreambase object.

strstreambase::strstreambase()

create a strstreambase object, with dynamic allocation

Synopsis:

#include <strstrea.h>
protected:
strstreambase::strstreambase();
strstreambase::strstreambase( char *str,
                              int len,
                              char *pstart );

Semantics:

There are two forms of the protected strstreambase constructor:

The first creates a strstreambase object that's initialized, but empty. Dynamic allocation is used to store characters. No buffer is allocated. A buffer is be allocated when data is first written to the strstreambase object.
This form of the protected strstreambase constructor is only used implicitly by the compiler when it generates a constructor for a derived class.
The second form creates a strstreambase object that's initialized and uses the buffer specified by the str and len parameters as its reserve area within the associated strstreambuf object. Dynamic allocation isn't used.
This form of the protected strstreambase constructor is unlikely to be explicitly used, except in the member initializer list for the constructor of a derived class.
The str, len and pstart parameters are interpreted as follows:
1. The buffer starts at str.
2. If len is positive, the buffer is len characters long.
3. If len is zero, str is a pointer to a C string that's terminated by a null character, and the length of the buffer is the length of the string.
4. If len is negative, the buffer is unbounded. This form should be used with extreme caution, since no buffer is truly unlimited in size, and it would be easy to write beyond the available space.
5. If the pstart parameter is NULL, the strstreambase object is read-only.
6. Otherwise, pstart divides the buffer into two regions. The get area starts at str and ends at pstart -1. The put area starts at pstart and goes to the end of the buffer.

Results:

The protected strstreambase constructor creates an initialized strstreambase object.

strstreambase::~strstreambase()

destroy a strstreambase object

Synopsis:

#include <strstrea.h>
protected:
strstreambase::~strstreambase();

Semantics:

The protected strstreambase destructor doesn't do anything explicit. The call to it is inserted implicitly by the compiler at the point where the strstreambase object goes out of scope.

Results:

The strstreambase object is destroyed.

`strstreambuf` Class

Declared:

strstrea.h

Derived from:

streambuf

The strstreambuf class is derived from the streambuf class, and provides additional functionality required to write characters to and read characters from a string buffer. Read and write operations can occur at different positions in the string buffer, since the get pointer and put pointer aren't necessarily connected. Seek operations are also supported.

The reserve area used by the strstreambuf object may be either fixed in size or dynamic. Generally, input strings are of a fixed size, while output streams are dynamic, since the final size might not be predictable. For dynamic buffers, the strstreambuf object automatically grows the buffer when necessary.

When writing is occurring and the put area is full, the overflow() virtual member function reallocates the buffer to a larger size (if possible), the put area is extended and the writing continues.
If reading is occurring and the get area is empty, the underflow() virtual member function checks to see if the put area is present and not empty. If so, the get area is extended to overlap the put area.

C++ programmers who wish to use string streams without deriving new objects will probably never explicitly create or use a strstreambuf object.

Protected Member Functions

The following member function is declared in the protected interface:

virtual int doallocate();

Public Member Functions

The following member functions are declared in the public interface:

strstreambuf();
strstreambuf( int );
strstreambuf( void *(*)( long ), void (*)( void * ) );
strstreambuf( char *, int, char * = 0 );
~strstreambuf();
int alloc_size_increment( int );
void freeze( int = 1 );
char *str();
virtual int overflow( int = EOF );
virtual int underflow();
virtual streambuf *setbuf( char *, int );
virtual streampos seekoff( streamoff,
                           ios::seekdir,
                           ios::openmode );
virtual int sync();

strstreambuf::alloc_size_increment()

modify the allocation size

Synopsis:

#include <strstrea.h>
public:
int strstreambuf::alloc_size_increment( 
    int increment );

Semantics:

The alloc_size_increment() public member function modifies the allocation size used when the buffer is first allocated or reallocated by dynamic allocation. The increment parameter is added to the previous allocation size for future use.

This function is a WATCOM extension.

Results:

The alloc_size_increment() public member function returns the previous value of the allocation size.

strstreambuf::doallocate()

deal with the put area when it's full

Synopsis:

#include <strstrea.h>
protected:
virtual int strstreambuf::doallocate();

Semantics:

The doallocate() protected virtual member function is called by the allocate() member function when it's determined that the put area is full and needs to be extended.

The doallocate() protected virtual member function performs the following steps:

If dynamic allocation isn't being used, the function fails.
A new size for the buffer is determined. If the allocation size is bigger than the current size, the allocation size is used. Otherwise, the buffer size is increased by DEFAULT_MAINBUF_SIZE, which is 512.
A new buffer is allocated. If an allocation function was specified in the constructor for the strstreambuf object, that allocation function is used, otherwise the operator new() intrinsic function is used. If the allocation fails, the doallocate() protected virtual member function fails.
If necessary, the contents of the get area are copied to the newly allocated buffer, and the get area pointers are adjusted accordingly.
The contents of the put area are copied to the newly allocated buffer, and the put area pointers are adjusted accordingly, extending the put area to the end of the new buffer.
The old buffer is freed. If a free function was specified in the constructor for the strstreambuf object, that free function is used, otherwise the operator delete() intrinsic function is used.

Results:

The doallocate() protected virtual member function returns __NOT_EOF on success, otherwise it returns EOF.

strstreambuf::freeze()

enable and disable automatic deletion of the reserve area

Synopsis:

#include <strstrea.h>
public:
void strstreambuf::freeze( int frozen = 1 );

Semantics:

The freeze() public member function enables and disables automatic deletion of the reserve area. If the freeze() public member function is called with no parameter or a non-zero parameter, the strstreambuf object is frozen. If the freeze() public member function is called with a zero parameter, the strstreambuf object is unfrozen.

A frozen strstreambuf object doesn't free the reserve area in the destructor. If the strstreambuf object is destroyed while it's frozen, it's the program's responsibility to free the reserve area.

If characters are written to the strstreambuf object while it's frozen, the effect is undefined, since the reserve area might be reallocated and therefore might move. However, if the strstreambuf object is frozen and then unfrozen, characters may be written to it.

Results:

The freeze() public member function returns the previous frozen state.

strstreambuf::overflow()

attempt to grow the put area

Synopsis:

#include <strstrea.h>
public:
virtual int strstreambuf::overflow( int ch = EOF );

Semantics:

The overflow() public virtual member function provides the output communication between the streambuf member functions and the strstreambuf object. Member functions in the streambuf class call the overflow() public virtual member function when the put area is full. The overflow() public virtual member function attempts to grow the put area so that writing may continue.

The overflow() public virtual member function performs the following steps:

If dynamic allocation isn't being used, the put area can't be extended, so the overflow() public virtual member function fails.
If dynamic allocation is being used, a new buffer is allocated using the doallocate() member function. It handles copying the contents of the old buffer to the new buffer and discarding the old buffer.
If the ch parameter isn't EOF, it's added to the end of the extended put area and the put pointer is advanced.

Results:

The overflow() public virtual member function returns __NOT_EOF when it successfully extends the put area, otherwise it returns EOF.

strstreambuf::seekoff()

position the get pointer and/or put pointer

Synopsis:

#include <strstrea.h>
public:
virtual streampos strstreambuf::seekoff( 
                           streamoff offset,
                           ios::seekdir dir,
                           ios::openmode mode );

Semantics:

The seekoff() public virtual member function positions the get pointer and/or put pointer at the specified position in the reserve area:

If the get pointer is moved, it's moved to a position relative to the start of the reserve area (which is also the start of the get area). If a position is specified that's beyond the end of the get area but is in the put area, the get area is extended to include the put area.
If the put pointer is moved, it's moved to a position relative to the start of the put area, not relative to the start of the reserve area.

The seekoff() public virtual member function seeks offset bytes from the position specified by the dir parameter.

The mode parameter may be ios::in, ios::out, or ios::in|ios::out, and should be interpreted as follows, provided the interpretation is meaningful:

ios::in: the get pointer should be moved.
ios::out: the put pointer should be moved.
ios::in|ios::out: both the get pointer and the put pointer should be moved.

If mode has any other value, the seekoff() public virtual member function fails. ios::in|ios::out isn't valid if the dir parameter is ios::cur.

The dir parameter may be ios::beg, ios::cur, or ios::end and is interpreted in conjunction with the offset parameter as follows:

ios::beg: the offset is relative to the start, and should be a positive value.
ios::cur: the offset is relative to the current position, and may be positive (seek towards end) or negative (seek towards start).
ios::end: the offset is relative to the end, and should be a negative value.

If the dir parameter has any other value, or the offset parameter doesn't have an appropriate sign, the seekoff() public virtual member function fails.

Results:

The seekoff() public virtual member function returns the new position in the file on success, otherwise it returns EOF. If both of ios::in|ios::out are specified, and the dir parameter is ios::cur the returned position refers to the put pointer.

strstreambuf::setbuf()

control the size of dynamic allocations

Synopsis:

#include <strstrea.h>
public:
virtual streambuf *strstreambuf::setbuf( 
    char *, 
    int size );

Semantics:

The setbuf() public virtual member function is used to control the size of the allocations when the strstreambuf object is using dynamic allocation. The first parameter is ignored. The next time an allocation is required, at least the number of characters specified in the size parameter is allocated. If the specified size isn't sufficient, the allocation reverts to its default behavior, which is to extend the buffer by DEFAULT_MAINBUF_SIZE, which is 512 characters.

If a program is going to write a large number of characters to the strstreambuf object, it should call the setbuf() public virtual member function to indicate the size of the next allocation, to prevent multiple allocations as the buffer gets larger.

Results:

The setbuf() public virtual member function returns a pointer to the strstreambuf object.

strstreambuf::str()

freeze the object, and return a pointer to the reserve area

Synopsis:

#include <strstrea.h>
public:
char *strstreambuf::str();

Semantics:

The str() public member function freezes the strstreambuf object and returns a pointer to the reserve area. This pointer remains valid after the strstreambuf object is destroyed, provided the strstreambuf object remains frozen, since the destructor doesn't free the reserve area if it's frozen.

The returned pointer might be NULL if the strstreambuf object is using dynamic allocation but hasn't yet had anything written to it.

If the strstreambuf object isn't using dynamic allocation, the pointer returned by the str() public member function is the same buffer pointer provided to the constructor. For a strstreambuf object using dynamic allocation, the pointer points to a dynamically allocated area.

The reserve area doesn't necessarily end with a null character. If the pointer returned by the str() public member function is to be interpreted as a C string, it's the program's responsibility to ensure that the null character is present.

Results:

The str() public member function returns a pointer to the reserve area and freezes the strstreambuf object.

strstreambuf::strstreambuf()

create a strstreambuf object

Synopsis:

#include <strstrea.h>
public:
strstreambuf::strstreambuf();
strstreambuf::strstreambuf( int alloc_size );
strstreambuf::strstreambuf( 
    void * (*alloc_fn)( long ),
    void   (*free_fn)( void * ) );
strstreambuf::strstreambuf( char *str,
                  int len,
                  char *pstart = NULL );
strstreambuf::strstreambuf( signed char *str,
                  int len,
                  signed char *pstart = NULL );
strstreambuf::strstreambuf( unsigned char *str,
                  int len,
                  unsigned char *pstart = NULL );

Semantics:

There are six forms of the public strstreambuf constructor:

The first creates an empty strstreambuf object that uses dynamic allocation.
No reserve area is allocated to start. Whenever characters are written to extend the strstreambuf object, the reserve area is reallocated and copied as required. The size of allocation is determined by the strstreambuf object, unless the setbuf() or alloc_size_increment member functions are called to change the allocation size. The default allocation size is determined by the constant DEFAULT_MAINBUF_SIZE, which is 512.

The second form creates an empty strstreambuf object that uses dynamic allocation.

No buffer is allocated to start. Whenever characters are written to extend the strstreambuf object, the reserve area is reallocated and copied as required. The size of the first allocation is determined by the alloc_size parameter, unless changed by a call to the setbuf() or alloc_size_increment member functions.

The alloc_size parameter is the starting reserve area size. When the reserve area is reallocated, the strstreambuf object uses DEFAULT_MAINBUF_SIZE to increase the reserve area size, unless the setbuf() or alloc_size_increment member functions have been called to specify a new allocation size.

The third form creates an empty strstreambuf object that uses dynamic allocation.
No buffer is allocated to start. Whenever characters are written to extend the strstreambuf object, the reserve area is reallocated and copied as required, using the specified alloc_fn and free_fn functions. The size of allocation is determined by the class unless the setbuf() or alloc_size_increment() member functions are called to change the allocation size. The default allocation size is determined by the constant DEFAULT_MAINBUF_SIZE, which is 512.
When a new reserve area is allocated, the function specified by the alloc_fn parameter is called with a long integer value indicating the number of bytes to allocate. If alloc_fn is NULL, the operator new() intrinsic function is used. Likewise, when the reserve area is freed, the function specified by the free_fn parameter is called with the pointer returned by the alloc_fn function as the parameter. If free_fn is NULL, the operator delete() intrinsic function is used.
The last three forms of the public strstreambuf constructor create a strstreambuf object that doesn't use dynamic allocation. The strstreambuf object is said to be using static allocation. The str and len parameters specify the bounds of the reserve area.
The str, len and pstart parameters are interpreted as follows:
1. The buffer starts at str.
2. If len is positive, the buffer is len characters long.
3. If len is zero, str is a pointer to a C string that's terminated by a null character, and the length of the buffer is the length of the string.
4. If len is negative, the buffer is unbounded. This form should be used with extreme caution, since no buffer is truly unlimited in size, and it would be easy to write beyond the available space.
5. If the pstart parameter is NULL, the strstreambuf object is read-only.
6. Otherwise, pstart divides the buffer into two regions. The get area starts at str, and ends at pstart -1. The put area starts at pstart, and goes to the end of the buffer.
If the get area is exhausted and characters have been written to the put area, the get area is extended to include the put area.
Note that the get pointer and put pointer don't necessarily point at the same position in the reserve area, so a read followed by a write doesn't imply that the write stores following the last character read. The get pointer is positioned following the last read operation, and the put pointer is positioned following the last write operation, unless the seekoff() member function has been used to reposition the pointer(s).

Results:

The public strstreambuf constructor creates a strstreambuf object.

strstreambuf::~strstreambuf()

destroy a strstreambuf object

Synopsis:

#include <strstrea.h>
public:
strstreambuf::~strstreambuf();

Semantics:

The public strstreambuf destructor destroys the strstreambuf object after discarding the reserve area.

The reserve area is discarded only if the strstreambuf object is using dynamic allocation and isn't frozen. The reserve area is freed using the free function specified by the form of the constructor that allows specification of the allocate and free functions, or using the operator delete() intrinsic function.

If the strstreambuf object is frozen or is using static allocation, the user of the strstreambuf object must have a pointer to the reserve area, and is responsible for freeing it.

The call to the public strstreambuf destructor is inserted implicitly by the compiler at the point where the strstreambuf object goes out of scope.

Results:

The strstreambuf object is destroyed.

strstreambuf::sync()

does nothing

Synopsis:

#include <strstrea.h>
public:
virtual int strstreambuf::sync();

Semantics:

The sync() public virtual member function does nothing because there's no external device with which to synchronize.

Results:

The sync() public virtual member function returns __NOT_EOF.

strstreambuf::underflow()

extend the get area, if possible

Synopsis:

#include <strstrea.h>
public:
virtual int strstreambuf::underflow();

Semantics:

The underflow() public virtual member function provides the input communication between the streambuf member functions and the strstreambuf object. Member functions in the streambuf class call the underflow() public virtual member function when the get area is empty.

If there's a non-empty put area present following the get area, the get area is extended to include the put area, allowing the input operation to continue using the put area. Otherwise the get area can't be extended.

Results:

The underflow() public virtual member function returns the first available character in the get area on successful extension, otherwise EOF is returned.

See also:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics:

See also:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics:

Results:

See also:

See also:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics:

Results:

See also:

See also:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics:

Results:

See also:

Synopsis:

Semantics: