The previous chapter referred in passing to the classes ostream
and istream, for output and input respectively. These classes
share certain properties, captured in their base class ios.
ios
The base class ios provides methods to test and manage the state
of input or output streams.
ios delegates the job of actually reading and writing bytes to
the abstract class streambuf, which is designed to provide
buffered streams (compatible with C, in the GNU implementation).
See section Using the streambuf Layer, for information on
the facilities available at the streambuf level.
ios constructor by default initializes a new ios, and
if you supply a streambuf sb to associate with it, sets the
state good in the new ios object. It also sets the
default properties of the new object.
You can also supply an optional second argument tie to the
constructor: if present, it is an initial value for ios::tie, to
associate the new ios object with another stream.
ios destructor is virtual, permitting application-specific
behavior when a stream is closed--typically, the destructor frees any
storage associated with the stream and releases any other associated
objects.
Use this collection of methods to test for (or signal) errors and other exceptional conditions of streams:
ios::fail is not true). For example, you might ask for
input on cin only if all prior output operations succeeded:
if (cout)
{
// Everything OK so far
cin >> new_value;
...
}
! returns true if ios::fail is true (an operation
has failed). For example,
you might issue an error message if input failed:
if (!cin)
{
// Oops
cerr << "Eh?\n";
}
iostate. You can test for any combination of
goodbit
eofbit
failbit
badbit
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.
ios::badbit is set.)
ios::eofbit
is set.)
ios::failbit or ios::badbit is set.)
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.
These methods control (or report on) settings for some details of controlling streams, primarily to do with formatting output:
setfill. See section Changing stream properties using manipulators.
Default: blank.
Default: 6.
You can also use the manipulator setprecision for this purpose.
See section Changing stream properties using manipulators.
Default: 0, which means to use as many characters as necessary.
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.
ios::dec
ios::oct
ios::hex
setbase, or any of the manipulators dec, oct, or
hex; see section Changing stream properties using manipulators.)
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.
ios::fixed
ios::precision to set precision.
ios::left
ios::right
ios::internal
ios::scientific
ios::showbase
ios::showpoint
ios::showpos
ios::skipws
ios::stdio
stdio streams stdout and stderr after
each output operation (for programs that mix C and C++ output conventions).
ios::unitbuf
ios::uppercase
Use ios::setf or ios::unsetf to change one property at a
time.
ios::unsetf to cancel.)
ios::unsetf for another way of clearing flags.)
ios::setf. Returns the old values of those flags.
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.
ios::precision in `<<'
expressions with the manipulator `setprecision(signif)'; for
example,
cout << setprecision(2) << 4.567;
prints `4.6'. Requires `#include <iomanip.h>'.
ios::width in `<<' expressions
with the manipulator `setw(n)'; for example,
cout << setw(5) << 234;
prints ` 234' with two leading blanks. Requires `#include <iomanip.h>'.
10 (decimal), 8 (octal), or
16 (hexadecimal), change the base value for numeric
representations. Requires `#include <iomanip.h>'.
ios::fill.
Requires `#include <iomanip.h>'.
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:
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.
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.
ios instance. index, conventionally returned from
ios::xalloc, identifies what particular data you need.
ios.
ios
instance. index, originally returned from ios::xalloc,
identifies what particular pointer you need.
ios.
You can use these methods to synchronize related streams with one another:
0 means no stream is tied.
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.
streambufFinally, you can use this method to access the underlying object:
streambuf object that underlies this
ios.
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'.
ostream simply
allocates a new ios object.
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.
ostream
These methods write on an ostream (you may also use the operator
<<; see section Operators and Default Streams).
ostream,
beginning at the pointer string.
string may have any of these types: char*, unsigned
char*, signed char*.
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.
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.
ostreamYou can control the output position (on output streams that actually support positions, typically files) with these methods:
ostream::tellp). loc specifies an
absolute position in the output stream.
ios::seekdir):
beg
cur
end
ostream utilities
You may need to use these ostream methods for housekeeping:
ostream.
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.
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'.
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'.
istream constructor simply
allocates a new ios object and initializes the input counter (the
value reported by istream::gcount) to 0.
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.
Use these methods to read a single character from the input stream:
EOF) from the input stream, returning
it (coerced to an unsigned char) as the result.
&c.
Use these methods to read strings (for example, a line at a time) from the input stream:
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.
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.
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.
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.
\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.
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.
istream::scan, but takes a single va_list argument.
istreamUse these methods to control the current input position:
istream::seekg.
istream::tellg.
ios::beg
ios::cur
ios::end
istream utilities
Use these methods for housekeeping on istream objects:
istream in the
last unformatted input operation.
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.
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.
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.
EOF if this is not allowed. Putting
back the most recently read character is always allowed. (This method
corresponds to the C function ungetc.)
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.
iostream constructor simply
allocates a new ios object, and initializes the input counter
(the value reported by istream::gcount) to 0.
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.
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.