@deftypefn Method void ios::setstate (iostate state) Set the state flag for this stream to state in addition to any state flags already set. Synonym (for upward compatibility): ios::set.

See ios::clear to set the stream state without regard to existing state flags. See ios::good, ios::eof, ios::fail, and ios::bad, to test the state. @end deftypefn

@deftypefn Method int ios::good () const Test the state flags associated with this stream; true if no error indicators are set. @end deftypefn

@deftypefn Method int ios::bad () const Test whether a stream is marked as unusable. (Whether ios::badbit is set.) @end deftypefn

@deftypefn Method int ios::eof () const True if end of file was reached on this stream. (If ios::eofbit is set.) @end deftypefn

@deftypefn Method int ios::fail () const Test for any kind of failure on this stream: either some operation failed, or the stream is marked as bad. (If either ios::failbit or ios::badbit is set.) @end deftypefn

@deftypefn Method void ios::clear (iostate state) Set the state indication for this stream to the argument state. You may call ios::clear with no argument, in which case the state is set to good (no errors pending).

See ios::good, ios::eof, ios::fail, and ios::bad, to test the state; see ios::set or ios::setstate for an alternative way of setting the state. @end deftypefn

Choices in formatting

These methods control (or report on) settings for some details of controlling streams, primarily to do with formatting output:

@deftypefn Method char ios::fill () const Report on the padding character in use. @end deftypefn

@deftypefn Method char ios::fill (char padding) Set the padding character. You can also use the manipulator setfill. See section Changing stream properties using manipulators.

Default: blank. @end deftypefn

@deftypefn Method int ios::precision () const Report the number of significant digits currently in use for output of floating point numbers.

Default: 6. @end deftypefn

@deftypefn Method int ios::precision (int signif) Set the number of significant digits (for input and output numeric conversions) to signif.

You can also use the manipulator setprecision for this purpose. See section Changing stream properties using manipulators. @end deftypefn

@deftypefn Method int ios::width () const Report the current output field width setting (the number of characters to write on the next << output operation).

Default: 0, which means to use as many characters as necessary. @end deftypefn

@deftypefn Method int ios::width (int num) Set the input field width setting to num. Return the previous value for this stream.

This value resets to zero (the default) every time you use <<; it is essentially an additional implicit argument to that operator. You can also use the manipulator setw for this purpose. See section Changing stream properties using manipulators. @end deftypefn

@deftypefn Method fmtflags ios::flags () const Return the current value of the complete collection of flags controlling the format state. These are the flags and their meanings when set:

@vtable @code

On input, if none of these flags is set, read numeric constants according to the prefix: decimal if no prefix (or a . suffix), octal if a 0 prefix is present, hexadecimal if a 0x prefix is present.

Default: dec.

@deftypefn Method fmtflags ios::flags (fmtflags value) Set value as the complete collection of flags controlling the format state. The flag values are described under ios::flags ().

Use ios::setf or ios::unsetf to change one property at a time. @end deftypefn

@deftypefn Method fmtflags ios::setf (fmtflags flag) Set one particular flag (of those described for ios::flags (); return the complete collection of flags previously in effect. (Use ios::unsetf to cancel.) @end deftypefn

@deftypefn Method fmtflags ios::setf (fmtflags flag, fmtflags mask) Clear the flag values indicated by mask, then set any of them that are also in flag. (Flag values are described for ios::flags ().) Return the complete collection of flags previously in effect. (See ios::unsetf for another way of clearing flags.) @end deftypefn

@deftypefn Method fmtflags ios::unsetf (fmtflags flag) Make certain flag (a combination of flag values described for ios::flags ()) is not set for this stream; converse of ios::setf. Returns the old values of those flags. @end deftypefn

Changing stream properties using manipulators

For convenience, manipulators provide a way to change certain properties of streams, or otherwise affect them, in the middle of expressions involving << or >>. For example, you might write

cout << "|" << setfill('*') << setw(5) << 234 << "|";

to produce |**234| as output.

@deftypefn Manipulator {} ws Skip whitespace. @end deftypefn

@deftypefn Manipulator {} flush Flush an output stream. For example, cout << ... < has the same effect as cout << ...; cout.flush();. @end deftypefn

@deftypefn Manipulator {} endl Write an end of line character \n, then flushes the output stream. @end deftypefn

@deftypefn Manipulator {} ends Write \0 (the string terminator character). @end deftypefn

@deftypefn Manipulator {} setprecision (int signif) You can change the value of ios::precision in << expressions with the manipulator setprecision(signif); for example,

cout << setprecision(2) << 4.567;

prints 4.6. Requires #include . @end deftypefn

@deftypefn Manipulator {} setw (int n) You can change the value of ios::width in << expressions with the manipulator setw(n); for example,

cout << setw(5) << 234;

prints 234 with two leading blanks. Requires #include . @end deftypefn

@deftypefn Manipulator {} setbase (int base) Where base is one of 10 (decimal), 8 (octal), or 16 (hexadecimal), change the base value for numeric representations. Requires #include . @end deftypefn

@deftypefn Manipulator {} dec Select decimal base; equivalent to setbase(10). @end deftypefn

@deftypefn Manipulator {} hex Select hexadecimal base; equivalent to setbase(16). @end deftypefn

@deftypefn Manipulator {} oct Select octal base; equivalent to setbase(8). @end deftypefn

@deftypefn Manipulator {} setfill (char padding) Set the padding character, in the same way as ios::fill. Requires #include . @end deftypefn

Extended data fields

A related collection of methods allows you to extend this collection of flags and parameters for your own applications, without risk of conflict between them:

@deftypefn Method {static fmtflags} ios::bitalloc () Reserve a bit (the single bit on in the result) to use as a flag. Using bitalloc guards against conflict between two packages that use ios objects for different purposes.

This method is available for upward compatibility, but is not in the ANSI working paper. The number of bits available is limited; a return value of 0 means no bit is available. @end deftypefn

@deftypefn Method {static int} ios::xalloc () Reserve space for a long integer or pointer parameter. The result is a unique nonnegative integer. You can use it as an index to ios::iword or ios::pword. Use xalloc to arrange for arbitrary special-purpose data in your ios objects, without risk of conflict between packages designed for different purposes. @end deftypefn

@deftypefn Method long& ios::iword (int index) Return a reference to arbitrary data, of long integer type, stored in an ios instance. index, conventionally returned from ios::xalloc, identifies what particular data you need. @end deftypefn

@deftypefn Method long ios::iword (int index) const Return the actual value of a long integer stored in an ios. @end deftypefn

@deftypefn Method void*& ios::pword (int index) Return a reference to an arbitrary pointer, stored in an ios instance. index, originally returned from ios::xalloc, identifies what particular pointer you need. @end deftypefn

@deftypefn Method void* ios::pword (int index) const Return the actual value of a pointer stored in an ios. @end deftypefn

Synchronizing related streams

You can use these methods to synchronize related streams with one another:

@deftypefn Method ostream* ios::tie () const Report on what output stream, if any, is to be flushed before accessing this one. A pointer value of 0 means no stream is tied. @end deftypefn

@deftypefn Method ostream* ios::tie (ostream* assoc) Declare that output stream assoc must be flushed before accessing this stream. @end deftypefn

@deftypefn Method int ios::sync_with_stdio ([int switch]) Unless iostreams and C stdio are designed to work together, you may have to choose between efficient C++ streams output and output compatible with C stdio. Use ios::sync_with_stdio() to select C compatibility.

The argument switch is a GNU extension; use 0 as the argument to choose output that is not necessarily compatible with C stdio. The default value for switch is 1.

If you install the stdio implementation that comes with GNU libio, there are compatible input/output facilities for both C and C++. In that situation, this method is unnecessary---but you may still want to write programs that call it, for portability. @end deftypefn

Reaching the underlying streambuf

Finally, you can use this method to access the underlying object:

@deftypefn Method streambuf* ios::rdbuf () const Return a pointer to the streambuf object that underlies this ios. @end deftypefn

Managing output streams: class ostream

Objects of class ostream inherit the generic methods from ios, and in addition have the following methods available. Declarations for this class come from iostream.h.

@deftypefn Constructor {} ostream::ostream () The simplest form of the constructor for an ostream simply allocates a new ios object. @end deftypefn

@deftypefn Constructor {} ostream::ostream (streambuf* sb [, ostream tie]) This alternative constructor requires a first argument sb of type streambuf*, to use an existing open stream for output. It also accepts an optional second argument tie, to specify a related ostream* as the initial value for ios::tie.

If you give the ostream a streambuf explicitly, using this constructor, the sb is not destroyed (or deleted or closed) when the ostream is destroyed. @end deftypefn

Writing on an ostream

These methods write on an ostream (you may also use the operator <<; see section Operators and Default Streams).

@deftypefn Method ostream& ostream::put (char c) Write the single character c. @end deftypefn

@deftypefn Method ostream& ostream::write (string, int length) Write length characters of a string to this ostream, beginning at the pointer string.

string may have any of these types: char*, unsigned char*, signed char*. @end deftypefn

@deftypefn Method ostream& ostream::form (const char *format, ...) A GNU extension, similar to fprintf(file, format, ...).

format is a printf-style format control string, which is used to format the (variable number of) arguments, printing the result on this ostream. See ostream::vform for a version that uses an argument list rather than a variable number of arguments. @end deftypefn

@deftypefn Method ostream& ostream::vform (const char *format, va_list args) A GNU extension, similar to vfprintf(file, format, args).

format is a printf-style format control string, which is used to format the argument list args, printing the result on this ostream. See ostream::form for a version that uses a variable number of arguments rather than an argument list. @end deftypefn

Repositioning an ostream

You can control the output position (on output streams that actually support positions, typically files) with these methods:

@deftypefn Method streampos ostream::tellp () Return the current write position in the stream. @end deftypefn

@deftypefn Method ostream& ostream::seekp (streampos loc) Reset the output position to loc (which is usually the result of a previous call to ostream::tellp). loc specifies an absolute position in the output stream. @end deftypefn

@deftypefn Method ostream& ostream::seekp (streamoff loc, rel) Reset the output position to loc, relative to the beginning, end, or current output position in the stream, as indicated by rel (a value from the enumeration ios::seekdir):

@vtable @code

Miscellaneous ostream utilities

You may need to use these ostream methods for housekeeping:

@deftypefn Method ostream& flush () Deliver any pending buffered output for this ostream. @end deftypefn

@deftypefn Method int ostream::opfx () opfx is a prefix method for operations on ostream objects; it is designed to be called before any further processing. See ostream::osfx for the converse.

opfx tests that the stream is in state good, and if so flushes any stream tied to this one.

The result is 1 when opfx succeeds; else (if the stream state is not good), the result is 0. @end deftypefn

@deftypefn Method void ostream::osfx () osfx is a suffix method for operations on ostream objects; it is designed to be called at the conclusion of any processing. All the ostream methods end by calling osfx. See ostream::opfx for the converse.

If the unitbuf flag is set for this stream, osfx flushes any buffered output for it.

If the stdio flag is set for this stream, osfx flushes any output buffered for the C output streams stdout and stderr. @end deftypefn

Managing input streams: class istream

Class istream objects are specialized for input; as for ostream, they are derived from ios, so you can use any of the general-purpose methods from that base class. Declarations for this class also come from iostream.h.

@deftypefn Constructor {} istream::istream () When used without arguments, the istream constructor simply allocates a new ios object and initializes the input counter (the value reported by istream::gcount) to 0. @end deftypefn

@deftypefn Constructor {} istream::istream (streambuf *sb [, ostream tie]) You can also call the constructor with one or two arguments. The first argument sb is a streambuf*; if you supply this pointer, the constructor uses that streambuf for input. You can use the second optional argument tie to specify a related output stream as the initial value for ios::tie.

If you give the istream a streambuf explicitly, using this constructor, the sb is not destroyed (or deleted or closed) when the ostream is destroyed. @end deftypefn

Reading one character

Use these methods to read a single character from the input stream:

@deftypefn Method int istream::get () Read a single character (or EOF) from the input stream, returning it (coerced to an unsigned char) as the result. @end deftypefn

@deftypefn Method istream& istream::get (char& c) Read a single character from the input stream, into &c. @end deftypefn

@deftypefn Method int istream::peek () Return the next available input character, but without changing the current input position. @end deftypefn

Reading strings

Use these methods to read strings (for example, a line at a time) from the input stream:

@deftypefn Method istream& istream::get (char* c, int len [, char delim]) Read a string from the input stream, into the array at c.

The remaining arguments limit how much to read: up to len-1 characters, or up to (but not including) the first occurrence in the input of a particular delimiter character delim---newline (\n) by default. (Naturally, if the stream reaches end of file first, that too will terminate reading.)

If delim was present in the input, it remains available as if unread; to discard it instead, see iostream::getline.

get writes \0 at the end of the string, regardless of which condition terminates the read. @end deftypefn

@deftypefn Method istream& istream::get (streambuf& sb [, char delim]) Read characters from the input stream and copy them on the streambuf object sb. Copying ends either just before the next instance of the delimiter character delim (newline \n by default), or when either stream ends. If delim was present in the input, it remains available as if unread. @end deftypefn

@deftypefn Method istream& istream::getline (charptr, int len [, char delim]) Read a line from the input stream, into the array at charptr. charptr may be any of three kinds of pointer: char*, unsigned char*, or signed char*.

The remaining arguments limit how much to read: up to (but not including) the first occurrence in the input of a line delimiter character delim---newline (\n) by default, or up to len-1 characters (or to end of file, if that happens sooner).

If getline succeeds in reading a ``full line'', it also discards the trailing delimiter character from the input stream. (To preserve it as available input, see the similar form of iostream::get.)

If delim was not found before len characters or end of file, getline sets the ios::fail flag, as well as the ios::eof flag if appropriate.

getline writes a null character at the end of the string, regardless of which condition terminates the read. @end deftypefn

@deftypefn Method istream& istream::read (pointer, int len) Read len bytes into the location at pointer, unless the input ends first.

pointer may be of type char*, void*, unsigned char*, or signed char*.

If the istream ends before reading len bytes, read sets the ios::fail flag. @end deftypefn

@deftypefn Method istream& istream::gets (char **s [, char delim]) A GNU extension, to read an arbitrarily long string from the current input position to the next instance of the delim character (newline \n by default).

To permit reading a string of arbitrary length, gets allocates whatever memory is required. Notice that the first argument s is an address to record a character pointer, rather than the pointer itself. @end deftypefn

@deftypefn Method istream& istream::scan (const char *format ...) A GNU extension, similar to fscanf(file, format, ...). The format is a scanf-style format control string, which is used to read the variables in the remainder of the argument list from the istream. @end deftypefn

@deftypefn Method istream& istream::vscan (const char *format, va_list args) Like istream::scan, but takes a single va_list argument. @end deftypefn

Repositioning an istream

Use these methods to control the current input position:

@deftypefn Method streampos istream::tellg () Return the current read position, so that you can save it and return to it later with istream::seekg. @end deftypefn

@deftypefn Method istream& istream::seekg (streampos p) Reset the input pointer (if the input device permits it) to p, usually the result of an earlier call to istream::tellg. @end deftypefn

@deftypefn Method istream& istream::seekg (streamoff offset, ios::seek_dir ref) Reset the input pointer (if the input device permits it) to offset characters from the beginning of the input, the current position, or the end of input. Specify how to interpret offset with one of these values for the second argument:

@vtable @code

Miscellaneous istream utilities

Use these methods for housekeeping on istream objects:

@deftypefn Method int istream::gcount () Report how many characters were read from this istream in the last unformatted input operation. @end deftypefn

@deftypefn Method int istream::ipfx (int keepwhite) Ensure that the istream object is ready for reading; check for errors and end of file and flush any tied stream. ipfx skips whitespace if you specify 0 as the keepwhite argument, and ios::skipws is set for this stream.

To avoid skipping whitespace (regardless of the skipws setting on the stream), use 1 as the argument.

Call istream::ipfx to simplify writing your own methods for reading istream objects. @end deftypefn

@deftypefn Method void istream::isfx () A placeholder for compliance with the draft ANSI standard; this method does nothing whatever.

If you wish to write portable standard-conforming code on istream objects, call isfx after any operation that reads from an istream; if istream::ipfx has any special effects that must be cancelled when done, istream::isfx will cancel them. @end deftypefn

@deftypefn Method istream& istream::ignore ([int n] [, int delim]) Discard some number of characters pending input. The first optional argument n specifies how many characters to skip. The second optional argument delim specifies a ``boundary'' character: ignore returns immediately if this character appears in the input.

By default, delim is EOF; that is, if you do not specify a second argument, only the count n restricts how much to ignore (while input is still available).

If you do not specify how many characters to ignore, ignore returns after discarding only one character. @end deftypefn

@deftypefn Method istream& istream::putback (char ch) Attempts to back up one character, replacing the character backed-up over by ch. Returns EOF if this is not allowed. Putting back the most recently read character is always allowed. (This method corresponds to the C function ungetc.) @end deftypefn

@deftypefn Method istream& istream::unget () Attempt to back up one character. @end deftypefn

Input and output together: class iostream

If you need to use the same stream for input and output, you can use an object of the class iostream, which is derived from both istream and ostream.

The constructors for iostream behave just like the constructors for istream.

@deftypefn Constructor {} iostream::iostream () When used without arguments, the iostream constructor simply allocates a new ios object, and initializes the input counter (the value reported by istream::gcount) to 0. @end deftypefn

@deftypefn Constructor {} iostream::iostream (streambuf* sb [, ostream* tie]) You can also call a constructor with one or two arguments. The first argument sb is a streambuf*; if you supply this pointer, the constructor uses that streambuf for input and output.

You can use the optional second argument tie (an ostream*) to specify a related output stream as the initial value for ios::tie. @end deftypefn

As for ostream and istream, iostream simply uses the ios destructor. However, an iostream is not deleted by its destructor.

You can use all the istream, ostream, and ios methods with an iostream object.

Classes for Files and Strings

There are two very common special cases of input and output: using files, and using strings in memory.

libio defines four specialized classes for these cases:

@ftable @code

Reading and writing files

These methods are declared in fstream.h.

You can read data from class ifstream with any operation from class istream. There are also a few specialized facilities:

@deftypefn Constructor {} ifstream::ifstream () Make an ifstream associated with a new file for input. (If you use this version of the constructor, you need to call ifstream::open before actually reading anything) @end deftypefn

@deftypefn Constructor {} ifstream::ifstream (int fd) Make an ifstream for reading from a file that was already open, using file descriptor fd. (This constructor is compatible with other versions of iostreams for POSIX systems, but is not part of the ANSI working paper.) @end deftypefn

@deftypefn Constructor {} ifstream::ifstream (const char* fname [, int mode [, int prot]]) Open a file *fname for this ifstream object.

By default, the file is opened for input (with ios::in as mode). If you use this constructor, the file will be closed when the ifstream is destroyed.

You can use the optional argument mode to specify how to open the file, by combining these enumerated values (with | bitwise or). (These values are actually defined in class ios, so that all file-related streams may inherit them.) Only some of these modes are defined in the latest draft ANSI specification; if portability is important, you may wish to avoid the others.

@vtable @code

The last optional argument prot is specific to Unix-like systems; it specifies the file protection (by default 644). @end deftypefn

@deftypefn Method void ifstream::open (const char* fname [, int mode [, int prot]]) Open a file explicitly after the associated ifstream object already exists (for instance, after using the default constructor). The arguments, options and defaults all have the same meanings as in the fully specified ifstream constructor. @end deftypefn

You can write data to class ofstream with any operation from class ostream. There are also a few specialized facilities:

@deftypefn Constructor {} ofstream::ofstream () Make an ofstream associated with a new file for output. @end deftypefn

@deftypefn Constructor {} ofstream::ofstream (int fd) Make an ofstream for writing to a file that was already open, using file descriptor fd. @end deftypefn

@deftypefn Constructor {} ofstream::ofstream (const char* fname [, int mode [, int prot]]) Open a file *fname for this ofstream object.

By default, the file is opened for output (with ios::out as mode). You can use the optional argument mode to specify how to open the file, just as described for ifstream::ifstream.

The last optional argument prot specifies the file protection (by default 644). @end deftypefn

@deftypefn Destructor {} ofstream::~ofstream () The files associated with ofstream objects are closed when the corresponding object is destroyed. @end deftypefn

@deftypefn Method void ofstream::open (const char* fname [, int mode [, int prot]]) Open a file explicitly after the associated ofstream object already exists (for instance, after using the default constructor). The arguments, options and defaults all have the same meanings as in the fully specified ofstream constructor. @end deftypefn

The class fstream combines the facilities of ifstream and ofstream, just as iostream combines istream and ostream.

The class fstreambase underlies both ifstream and ofstream. They both inherit this additional method:

@deftypefn Method void fstreambase::close () Close the file associated with this object, and set ios::fail in this object to mark the event. @end deftypefn

Reading and writing in memory

The classes istrstream, ostrstream, and strstream provide some additional features for reading and writing strings in memory---both static strings, and dynamically allocated strings. The underlying class strstreambase provides some features common to all three; strstreambuf underlies that in turn.

@deftypefn Constructor {} istrstream::istrstream (const char* str [, int size]) Associate the new input string class istrstream with an existing static string starting at str, of size size. If you do not specify size, the string is treated as a NUL terminated string. @end deftypefn

@deftypefn Constructor {} ostrstream::ostrstream () Create a new stream for output to a dynamically managed string, which will grow as needed. @end deftypefn

@deftypefn Constructor {} ostrstream::ostrstream (char* str, int size [,int mode]) A new stream for output to a statically defined string of length size, starting at str. You may optionally specify one of the modes described for ifstream::ifstream; if you do not specify one, the new stream is simply open for output, with mode ios::out. @end deftypefn

@deftypefn Method int ostrstream::pcount () Report the current length of the string associated with this ostrstream. @end deftypefn

@deftypefn Method char* ostrstream::str () A pointer to the string managed by this ostrstream. Implies ostrstream::freeze(). @end deftypefn

@deftypefn Method void ostrstream::freeze ([int n]) If n is nonzero (the default), declare that the string associated with this ostrstream is not to change dynamically; while frozen, it will not be reallocated if it needs more space, and it will not be deallocated when the ostrstream is destroyed. Use freeze(1) if you refer to the string as a pointer after creating it via ostrstream facilities.

freeze(0) cancels this declaration, allowing a dynamically allocated string to be freed when its ostrstream is destroyed.

If this ostrstream is already static---that is, if it was created to manage an existing statically allocated string---freeze is unnecessary, and has no effect. @end deftypefn

@deftypefn Method int ostrstream::frozen () Test whether freeze(1) is in effect for this string. @end deftypefn

@deftypefn Method strstreambuf* strstreambase::rdbuf () A pointer to the underlying strstreambuf. @end deftypefn

Using the streambuf Layer

The istream and ostream classes are meant to handle conversion between objects in your program and their textual representation.

By contrast, the underlying streambuf class is for transferring raw bytes between your program, and input sources or output sinks. Different streambuf subclasses connect to different kinds of sources and sinks.

The GNU implementation of streambuf is still evolving; we describe only some of the highlights.

Areas of a streambuf

Streambuf buffer management is fairly sophisticated (this is a nice way to say ``complicated''). The standard protocol has the following ``areas'':

• The put area contains characters waiting for output.

• The get area contains characters available for reading.

The GNU streambuf design extends this, but the details are still evolving.

C-style formatting for streambuf objects

The GNU streambuf class supports printf-like formatting and scanning.

@deftypefn Method int streambuf::vform (const char *format, ...) Similar to fprintf(file, format, ...). The format is a printf-style format control string, which is used to format the (variable number of) arguments, printing the result on the this streambuf. The result is the number of characters printed. @end deftypefn

@deftypefn Method int streambuf::vform (const char *format, va_list args) Similar to vfprintf(file, format, args). The format is a printf-style format control string, which is used to format the argument list args, printing the result on the this streambuf. The result is the number of characters printed. @end deftypefn

@deftypefn Method int streambuf::scan (const char *format, ...) Similar to fscanf(file, format, ...). The format is a scanf-style format control string, which is used to read the (variable number of) arguments from the this streambuf. The result is the number of items assigned, or EOF in case of input failure before any conversion. @end deftypefn

@deftypefn Method int streambuf::vscan (const char *format, va_list args) Like streambuf::scan, but takes a single va_list argument. @end deftypefn

Wrappers for C stdio

A stdiobuf is a streambuf object that points to a FILE object (as defined by stdio.h). All streambuf operations on the stdiobuf are forwarded to the FILE. Thus the stdiobuf object provides a wrapper around a FILE, allowing use of streambuf operations on a FILE. This can be useful when mixing C code with C++ code.

The pre-defined streams cin, cout, and cerr are normally implemented as stdiobuf objects that point to respectively stdin, stdout, and stderr. This is convenient, but it does cost some extra overhead.

If you set things up to use the implementation of stdio provided with this library, then cin, cout, and cerr will be set up to to use stdiobuf objects, since you get their benefits for free. See section C Input and Output.

Backing up

The GNU iostream library allows you to ask a streambuf to remember the current position. This allows you to go back to this position later, after reading further. You can back up arbitrary amounts, even on unbuffered files or multiple buffers' worth, as long as you tell the library in advance. This unbounded backup is very useful for scanning and parsing applications. This example shows a typical scenario:

// Read either "dog", "hound", or "hounddog".
// If "dog" is found, return 1.
// If "hound" is found, return 2.
// If "hounddog" is found, return 3.
// If none of these are found, return -1.
int my_scan(streambuf* sb)
{
    streammarker fence(sb);
    char buffer[20];
    // Try reading "hounddog":
    if (sb->sgetn(buffer, 8) == 8
        && strncmp(buffer, "hounddog", 8) == 0)
      return 3;
    // No, no "hounddog":  Back up to 'fence'
    sb->seekmark(fence); // 
    // ... and try reading "dog":
    if (sb->sgetn(buffer, 3) == 3
        && strncmp(buffer, "dog", 3) == 0)
      return 1;
    // No, no "dog" either:  Back up to 'fence'
    sb->seekmark(fence); // 
    // ... and try reading "hound":
    if (sb->sgetn(buffer, 5) == 5
        && strncmp(buffer, "hound", 5) == 0)
      return 2;
    // No, no "hound" either:  Back up and signal failure.
    sb->seekmark(fence); // Backup to 'fence'
    return -1;
}

@deftypefn Constructor {} streammarker::streammarker (streambuf* sbuf) Create a streammarker associated with sbuf that remembers the current position of the get pointer. @end deftypefn

@deftypefn Method int streammarker::delta (streammarker& mark2) Return the difference between the get positions corresponding to *this and mark2 (which must point into the same streambuffer as this). @end deftypefn

@deftypefn Method int streammarker::delta () Return the position relative to the streambuffer's current get position. @end deftypefn

@deftypefn Method int streambuffer::seekmark (streammarker& mark) Move the get pointer to where it (logically) was when mark was constructed. @end deftypefn

Forwarding I/O activity

An indirectbuf is one that forwards all of its I/O requests to another streambuf.

An indirectbuf can be used to implement Common Lisp synonym-streams and two-way-streams:

class synonymbuf : public indirectbuf {
   Symbol *sym;
   synonymbuf(Symbol *s) { sym = s; }
   virtual streambuf *lookup_stream(int mode) {
       return coerce_to_streambuf(lookup_value(sym)); }
};

C Input and Output

libio is distributed with a complete implementation of the ANSI C stdio facility. It is implemented using streambuf objects. See section Wrappers for C stdio package is intended as a replacement for the whatever stdio is in your C library. Since stdio works best when you build libc to contain it, and that may be inconvenient, it is not installed by default.

Extensions beyond ANSI:

• A stdio FILE is identical to a streambuf. Hence there is no need to worry about synchronizing C and C++ input/output---they are by definition always synchronized.

• If you create a new streambuf sub-class (in C++), you can use it as a FILE from C. Thus the system is extensible using the standard streambuf protocol.

• You can arbitrarily mix reading and writing, without having to seek in between.

• Unbounded ungetc() buffer.

Index