The GNU C++ Iostream Library - Stream Classes
Go to the , , ,
section, .
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.
: Shared properties.
: Managing output streams.
: Managing input streams.
: Input and output together.
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 , for information on
the facilities available at the streambuf level.
Constructor:
ios::ios ([streambuf* sb [, ostream* tie])
The 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.
Destructor:
ios::~ios ()
The 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
: Checking the state of a stream.
: Choices in formatting.
: Convenient ways of changing stream properties.
: Extended data fields.
: Synchronizing related streams.
: Reaching the underlying streambuf.
Use this collection of methods to test for (or signal) errors and other
exceptional conditions of streams:
Method: ios::operator void* () const
You can do a quick check on the state of the most recent operation on a
stream by examining a pointer to the stream itself.
The pointer is
arbitrary except it is true if no failures have
occurred (ios::fail is not true).
For example, you might ask for
input on cin only if all prior output operations succeeded:
// Everything OK so far
cin >> new_
Method: ios::operator ! () const
In case it is more convenient to check whether something has failed, the
operator ! returns true if ios::fail is true (an operation
has failed).
For example,
you might issue an error message if input failed:
cerr << "Eh?\n";
Method: iostate ios::rdstate () const
Return the state flags for this stream.
The value is from the
enumeration iostate.
You can test for any combination of
There are no indications of exceptional states on this stream.
End of file.
An operation has f this usually indicates bad
format of input.
The stream is unusable.
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):
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.
Method: int ios::good () const
Test the state flags associa true if no error
indicators are set.
Method: int ios::bad () const
Test whether a stream is marked as unusable.
ios::badbit is set.)
Method: int ios::eof () const
True if end of file was reached on this stream.
(If ios::eofbit
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.)
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, 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:
Method: char ios::fill () const
Report on the padding character in use.
Method: char ios::fill (char padding)
Set the padding character.
You can also use the manipulator
See section .
Default: blank.
Method: int ios::precision () const
Report the number of significant digits currently in use for output of
floating point numbers.
Default: 6.
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 .
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.
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.
also use the manipulator setw for this purpose.
See section .
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:
What numeric base to use in converting integers from internal to display
representation, or vice versa: decimal, octal, or hexadecimal,
respectively.
(You can change the base using the manipulator
setbase, or any of the manipulators dec, oct, or
hex; see section .)
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
Avoid scientific notation, and always show a fixed number of digits after
the decimal point, according to the output precision in effect.
Use ios::precision to set precision.
ios::right
ios::internal
Where output is to appear in a fixed- left-justified,
right-justified, or with padding in the middle (e.g. between a numeric
sign and the associated value), respectively.
ios::scientific
Use scientific (exponential) notation to display numbers.
ios::showbase
Display the conventional prefix as a visual indicator of the conversion
base: no prefix for decimal, `0' for octal, `0x' for hexadecimal.
ios::showpoint
Display a decimal point and trailing zeros after it to fill out numeric
fields, even when redundant.
ios::showpos
Display a positive sign on display of positive numbers.
ios::skipws
Skip white space.
(On by default).
ios::stdio
Flush the C stdio streams stdout and stderr after
each output operation (for programs that mix C and C++ output conventions).
ios::unitbuf
Flush after each output operation.
ios::uppercase
Use upper-case characters for the non-numeral elements in numeric
for instance, `0X7A' rather than `0x7a', or
`3.14E+09' rather than `3.14e+09'.
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
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.)
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
(See ios::unsetf for another way of clearing flags.)
Method: fmtflags ios::unsetf (fmtflags flag)
Make certain flag (a combination of flag values described for
`ios::flags ()') is not converse of
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
cout << "|" << setfill('*') << setw(5) << 234 << "|";
to produce `|**234|' as output.
Manipulator:
Skip whitespace.
Manipulator:
Flush an output stream.
For example, `cout << ... <<'
has the same effect as `cout << ...; cout.flush();'.
Manipulator:
Write an end of line character `\n', then flushes the output stream.
Manipulator:
Write `\0' (the string terminator character).
Manipulator:
setprecision (int signif)
You can change the value of ios::precision in `<<'
expressions with the manipulator `setprecision(signif)'; for
cout << setprecision(2) << 4.567;
prints `4.6'.
Requires `#include <iomanip.h>'.
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;
234' with two leading blanks.
Requires `#include
<iomanip.h>'.
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 <iomanip.h>'.
Manipulator:
S equivalent to `setbase(10)'.
Manipulator:
Sel equivalent to `setbase(16)'.
Manipulator:
S equivalent to `setbase(8)'.
Manipulator:
setfill (char padding)
Set the padding character, in the same way as 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:
Method: static fmtflags ios::bitalloc ()
Reserve a bit (the single bit on in the result) to use as a flag.
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
return value of 0 means no bit is available.
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.
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.
Method: long ios::iword (int index) const
Return the actual value of a long integer stored in an ios.
Method: void*& ios::pword (int index)
Return a reference to an arbitrary pointer, stored in an ios
index, originally returned from ios::xalloc,
identifies what particular pointer you need.
Method: void* ios::pword (int index) const
Return the actual value of a pointer stored in an ios.
You can use these methods to synchronize related streams with
one another:
Method: ostream* ios::tie () const
Report on what output stream, if any, is to be flushed before accessing
A pointer value of 0 means no stream is tied.
Method: ostream* ios::tie (ostream* assoc)
Declare that output stream assoc must be flushed before accessing
this stream.
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 use 0 as the
argument to choose output that is not necessarily compatible with C
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
In that situation, this method is unnecessary--but you may
still want to write programs that call it, for portability.
Finally, you can use this method to access the underlying object:
Method: streambuf* ios::rdbuf () const
Return a pointer to the streambuf object that underlies this
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'.
Constructor:
ostream::ostream ()
The simplest form of the constructor for an ostream simply
allocates a new ios object.
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.
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.
: Writing on an ostream.
: Repositioning an ostream.
: Miscellaneous ostream utilities.
These methods write on an ostream (you may also use the operator
<<; see section ).
Method: ostream& ostream::put (char c)
Write the single character c.
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*.
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.
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.
You can control the output position (on output streams that actually
support positions, typically files) with these methods:
Method: streampos ostream::tellp ()
Return the current write position in the stream.
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.
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):
Interpret loc as an absolute offset from the beginning of the
Interpret loc as an offset relative to the current output
Interpret loc as an offset from the current end of the output
You may need to use these ostream methods for housekeeping:
Method: ostream& flush ()
Deliver any pending buffered output for this ostream.
Method: int ostream::opfx ()
opfx is a prefix method for operations on ostream
it is designed to be called before any further processing.
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 else (if the stream state is
not good), the result is 0.
Method: void ostream::osfx ()
osfx is a suffix method for operations on ostream
it is designed to be called at the conclusion of any processing.
the ostream methods end by calling osfx.
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'.
Class istream objects are s 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'.
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.
Constructor:
istream::istream (streambuf *sb [, ostream tie])
You can also call the constructor with one or two arguments.
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.
: Reading one character.
: Reading strings.
: Repositioning an istream.
: Miscellaneous istream utilities.
Use these methods to read a single character from the input stream:
Method: int istream::get ()
Read a single character (or EOF) from the input stream, returning
it (coerced to an unsigned char) as the result.
Method: istream& istream::get (char& c)
Read a single character from the input stream, into &c.
Method: int istream::peek ()
Return the next available input character, but without changing
the current input position.
Use these methods to read strings (for example, a line at a time) from
the input stream:
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
to discard it instead, see iostream::getline.
get writes `\0' at the end of the string, regardless
of which condition terminates the read.
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.
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.
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.
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
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.
Method: istream& istream::vscan (const char *format, va_list args)
Like istream::scan, but takes a single va_list argument.
Use these methods to control the current input position:
Method: streampos istream::tellg ()
Return the current read position, so that you can save it and return to
it later with istream::seekg.
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.
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:
Interpret loc as an absolute offset from the beginning of the
Interpret loc as an offset relative to the current output
Interpret loc as an offset from the current end of the output
Use these methods for housekeeping on istream objects:
Method: int istream::gcount ()
Report how many characters were read from this istream in the
last unformatted input operation.
Method: int istream::ipfx (int keepwhite)
Ensure that the istream object
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.
Method: void istream::isfx ()
A placeholder for compliance with the draft ANSI 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.
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
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.
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.
back the most recently read character is always allowed.
(This method
corresponds to the C function ungetc.)
Method: istream& istream::unget ()
Attempt to back up one character.
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.
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.
Constructor:
iostream::iostream (streambuf* sb [, ostream* tie])
You can also call a constructor with one or two arguments.
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
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.
Go to the , , ,
section, .}