ios(3C++) ios(3C++)
NAME
ios - input/output formatting
SYNOPSIS
#include <iostream.h>
class ios {
public:
enum io_state { goodbit=0, eofbit, failbit,
badbit };
enum open_mode { in, out, ate, app, trunc, nocreate, noreplace };
enum seek_dir { beg, cur, end };
/* flags for controlling format */
enum { skipws=01,
left=02, right=04, internal=010,
dec=020, oct=040, hex=0100,
showbase=0200, showpoint=0400, uppercase=01000, showpos=02000,
scientific=04000, fixed=010000,
unitbuf=020000, stdio=040000 };
static const long basefield;
/* dec|oct|hex */
static const long adjustfield;
/* left|right|internal */
static const long floatfield;
/* scientific|fixed */
public:
ios(streambuf*);
int bad();
static long bitalloc();
void clear(int state =0);
int eof();
int fail();
char fill();
char fill(char);
long flags();
long flags(long);
int good();
long& iword(int);
int operator!();
operator void*();
int precision();
int precision(int);
streambuf* rdbuf();
void* & pword(int);
int rdstate();
Copyright 1994 Novell, Inc. Page 1
ios(3C++) ios(3C++)
long setf(long setbits, long field);
long setf(long);
static void sync_with_stdio();
ostream* tie();
ostream* tie(ostream*);
long unsetf(long);
int width();
int width(int);
static int xalloc();
protected:
ios();
init(streambuf*);
private:
ios(ios&);
void operator=(ios&) ;
};
/* Manipulators */
ios& dec(ios&) ;
ios& hex(ios&) ;
ios& oct(ios&) ;
ostream& endl(ostream& i) ;
ostream& ends(ostream& i) ;
ostream& flush(ostream&) ;
istream& ws(istream&) ;
DESCRIPTION
The stream classes derived from class ios provide a high level
interface that supports transferring formatted and unformatted
information into and out of streambufs. This manual page
describes the operations common to both input and output.
Several enumerations are declared in class ios, open_mode,
io_state, seek_dir, and format flags, to avoid polluting the
global name space. The io_states are described on this manual
page under ``Error States.'' The format fields are also
described on this page, under ``Formatting.'' The open_modes
are described in detail in fstream(3C++) under open(). The
seek_dirs are described in streambuf_pub(3C++) under
seekoff().
In the following descriptions assume:
- s and s2 are ioss.
- sr is an ios&.
- sp is a ios*.
- i, oi, j, and n are ints.
Copyright 1994 Novell, Inc. Page 2
ios(3C++) ios(3C++)
- l, f, and b are longs.
- c and oc are chars.
- osp and oosp are ostream*s.
- sb is a streambuf*.
- pos is a streampos.
- off is a streamoff.
- dir is a seek_dir.
- mode is an int representing an open_mode.
- fct is a function with type ios& (*)(ios&).
- vp is a void*&.
Constructors and assignment:
ios(sb)
The streambuf denoted by sb becomes the streambuf
associated with the constructed ios. If sb is null, the
effect is undefined.
ios(sr)
s2=s Copying of ioss is not well-defined in general,
therefore the constructor and assignment operators are
private so that the compiler will complain about
attempts to copy ios objects. Copying pointers to
iostreams is usually what is desired.
ios()
init(sb)
Because class ios is now inherited as a virtual base
class, a constructor with no arguments must be used.
This constructor is declared protected. Therefore
ios::init(streambuf*) is declared protected and must be
used for initialization of derived classes.
Error States
An ios has an internal error state (which is a collection of
the bits declared as io_states). Members related to the error
state are:
i=s.rdstate()
Returns the current error state.
s.clear(i)
Stores i as the error state. If i is zero, this clears
all bits except ios::hardfail (this bit is not for
public access). To set a bit without clearing
previously set bits requires something like
s.clear(ios::badbit|s.rdstate()).
Copyright 1994 Novell, Inc. Page 3
ios(3C++) ios(3C++)
i=s.good()
Returns non-zero if the error state has no bits set,
zero otherwise.
i=s.eof()
Returns non-zero if eofbit is set in the error state,
zero otherwise. Normally this bit is set when an end-
of-file has been encountered during an extraction.
i=s.fail()
Returns non-zero if either badbit or failbit is set in
the error state, zero otherwise. Normally this
indicates that some extraction or conversion has failed,
but the stream is still usable. That is, once the
failbit is cleared, I/O on s can usually continue.
i=s.bad()
Returns non-zero if badbit is set in the error state,
zero otherwise. This usually indicates that some
operation on s.rdbuf() has failed, a severe error, from
which recovery is probably impossible. That is, it will
probably be impossible to continue I/O operations on s.
Operators
Two operators are defined to allow convenient checking of the
error state of an ios: operator!() and operator void*(). The
latter converts an ios to a pointer so that it can be compared
to zero. The conversion will return 0 if failbit or badbit is
set in the error state, and will return a pointer value
otherwise. This pointer is not meant to be used. This allows
one to write expressions such as:
if ( cin ) ...
if ( cin >> x ) ...
The ! operator returns non-zero if failbit or badbit is set in
the error state, which allows expressions like the following
to be used:
if ( !cout ) ...
Copyright 1994 Novell, Inc. Page 4
ios(3C++) ios(3C++)
Formatting
An ios has a format state that is used by input and output
operations to control the details of formatting operations.
For other operations the format state has no particular effect
and its components may be set and examined arbitrarily by user
code. Most formatting details are controlled by using the
flags, setf, and unsetf functions to set the following flags,
which are declared in an enumeration in class ios. Three
other components of the format state are controlled separately
with the functions fill, width, and precision.
skipws
If skipws is set, whitespace will be skipped on input.
This applies to scalar extractions. When skipws is not
set, whitespace is not skipped before the extractor
begins conversion. If skipws is not set and a zero
length field is encountered, the extractor will signal
an error. Additionally, the arithmetic extractors will
signal an error if skipws is not set and a whitespace is
encountered.
left
right
internal
These flags control the padding of a value. When left
is set, the value is left-adjusted, that is, the fill
character is added after the value. When right is set,
the value is right-adjusted, that is, the fill character
is added before the value. When internal is set, the
fill character is added after any leading sign or base
indication, but before the value. Right-adjustment is
the default if none of these flags is set. These fields
are collectively identified by the static member,
ios::adjustfield. The fill character is controlled by
the fill() function, and the width of padding is
controlled by the width() function.
dec
oct
hex These flags control the conversion base of a value. The
conversion base is 10 (decimal) if dec is set, but if
oct or hex is set, conversions are done in octal or
hexadecimal, respectively. If none of these is set,
insertions are in decimal, but extractions are
interpreted according to the C++ lexical conventions for
integral constants. These fields are collectively
Copyright 1994 Novell, Inc. Page 5
ios(3C++) ios(3C++)
identified by the static member, ios::basefield. The
manipulators hex, dec, and oct can also be used to set
the conversion base; see ``Built-in Manipulators''
below.
showbase
If showbase is set, insertions will be converted to an
external form that can be read according to the C++
lexical conventions for integral constants. showbase is
unset by default.
showpos
If showpos is set, then a ``+'' will be inserted into a
decimal conversion of a positive integral value.
uppercase
If uppercase is set, then an upper case ``X'' will be
used for hexadecimal conversion when showbase is set, or
an upper case ``E'' will be used to print floating point
numbers in scientific notation.
showpoint
If showpoint is set, trailing zeros and decimal points
appear in the result of a floating point conversion.
scientific
fixed These flags control the format to which a floating point
value is converted for insertion into a stream. If
scientific is set, the value is converted using
scientific notation, where there is one digit before the
decimal point and the number of digits after it is equal
to the precision (see below), which is six by default.
An upper case ``E'' will introduce the exponent if
uppercase is set, a lower case ``e'' will appear
otherwise. If fixed is set, the value is converted to
decimal notation with precision digits after the decimal
point, or six by default. If neither scientific nor
fixed is set, then the value will be converted using
either notation, depending on the value; scientific
notation will be used if the exponent resulting from the
conversion is less than -4 or greater than or equal to
precision digits. Otherwise the value will be converted
to decimal notation with precision digits total. If
showpoint is not set, trailing zeroes are removed from
the result and a decimal point appears only if it is
followed by a digit. scientific and fixed are
Copyright 1994 Novell, Inc. Page 6
ios(3C++) ios(3C++)
collectively identified by the static member
ios::floatfield.
unitbuf
When set, a flush is performed by ostream::osfx() after
each insertion. Unit buffering provides a compromise
between buffered output and unbuffered output.
Performance is better under unit buffering than
unbuffered output, which makes a system call for each
character output. Unit buffering makes a system call
for each insertion operation, and doesn't require the
user to call ostream::flush().
stdio When set, stdout and stderr are flushed by
ostream::osfx() after each insertion. However, the
flush will not be in effect without a call to
ios::sync_with_stdio().
The following functions use and set the format flags and
variables.
oc=s.fill(c)
Sets the ``fill character'' format state variable to c
and returns the previous value. c will be used as the
padding character, if one is necessary (see width(),
below). The default fill or padding character is a
space. The positioning of the fill character is
determined by the right, left, and internal flags; see
above. A parameterized manipulator, setfill, is also
available for setting the fill character; see
manip(3C++).
c=s.fill()
Returns the ``fill character'' format state variable.
l=s.flags()
Returns the current format flags.
l=s.flags(f)
Resets all the format flags to those specified in f and
returns the previous settings.
oi=s.precision(i)
Sets the precision format state variable to i and
returns the previous value. This variable controls the
number of significant digits inserted by the floating
Copyright 1994 Novell, Inc. Page 7
ios(3C++) ios(3C++)
point inserter. The default is 6. A parameterized
manipulator, setprecision, is also available for setting
the precision; see manip(3C++).
i=s.precision()
Returns the precision format state variable.
l=s.setf(b)
Turns on in s the format flags marked in b and returns
the previous settings. A parameterized manipulator,
setiosflags, performs the same function; see
manip(3C++).
l=s.setf(b,f)
Resets in s only the format flags specified by f to the
settings marked in b, and returns the previous settings.
That is, the format flags specified by f are cleared in
s, then reset to be those marked in b. For example, to
change the conversion base in s to be hex, one could
write: s.setf(ios::hex,ios::basefield). ios::basefield
specifies the conversion base bits as candidates for
change, and ios::hex specifies the new value.
s.setf(0,f) will clear all the bits specified by f, as
will a parameterized manipulator, resetiosflags; see
manip(3C++).
l=s.unsetf(b)
Unsets in s the bits set in b and returns the previous
settings.
oi=s.width(i)
Sets the field width format variable to i and returns
the previous value. When the field width is zero (the
default), inserters will insert only as many characters
as necessary to represent the value being inserted.
When the field width is non-zero, the inserters will
insert at least that many characters, using the fill
character to pad the value, if the value being inserted
requires fewer than field-width characters to be
represented. However, the numeric inserters never
truncate values, so if the value being inserted will not
fit in field-width characters, more than field-width
characters will be output. The field width is always
interpreted as a minimum number of characters; there is
no direct way to specify a maximum number of characters.
The field-width format variable is reset to the default
Copyright 1994 Novell, Inc. Page 8
ios(3C++) ios(3C++)
(zero) after each insertion or extraction, and in this
sense it behaves as a parameter for insertions and
extractions. A parameterized manipulator, setw, is also
available for setting the width; see manip(3C++).
i=s.width()
Returns the field-width format variable.
User-defined Format Flags
Class ios can be used as a base class for derived classes that
require additional format flags or variables. The iostream
library provides several functions to do this. The two static
member functions ios::xalloc and ios::bitalloc, allow several
such classes to be used together without interference.
b=ios::bitalloc()
Returns a long with a single, previously unallocated,
bit set. This allows users who need an additional flag
to acquire one, and pass it as an argument to
ios::setf(), for example. If it returns 0, all
allocatable bits have been used.
i=ios::xalloc()
Returns a previously unused index into an array of words
available for use as format state variables by derived
classes. If it returns a negative value, all the
indices have been used.
l=s.iword(i)
When i is an index allocated by ios::xalloc, iword()
returns a reference to the ith user-defined word.
vp=s.pword(i)
When i is an index allocated by ios::xalloc, pword()
returns a reference to the ith user-defined word.
pword() is the same as iword() except that it is typed
differently.
Other members:
sb=s.rdbuf()
Returns a pointer to the streambuf associated with s
when s was constructed.
ios::sync_with_stdio()
Solves problems that arise when mixing stdio and
iostreams. The first time it is called it will reset
Copyright 1994 Novell, Inc. Page 9
ios(3C++) ios(3C++)
the standard iostreams (cin, cout, cerr, clog) to be
streams using stdiobufs. After that, input and output
using these streams may be mixed with input and output
using the corresponding FILEs (stdin, stdout, and
stderr) and will be properly synchronized.
sync_with_stdio() makes cout and cerr unit buffered (see
ios::unitbuf and ios::stdio above). Invoking
sync_with_stdio() degrades performance a variable
amount, depending on the length of the strings being
inserted (shorter strings incur a larger performance
hit).
oosp=s.tie(osp)
Sets the tie variable to osp, and returns its previous
value. This variable supports automatic ``flushing'' of
ioss. If the tie variable is non-null and an ios needs
more characters or has characters to be consumed, the
ios pointed at by the tie variable is flushed. By
default, cin is tied initially to cout so that attempts
to get more characters from standard input result in
flushing standard output. Additionally, cerr and clog
are tied to cout by default. For other ioss, the tie
variable is set to zero by default.
osp=s.tie()
Returns the tie variable.
Built-in Manipulators:
Some convenient manipulators (functions that take an ios&, an
istream&, or an ostream& and return their argument; see
manip(3C++)) are:
sr<<dec
sr>>dec
These set the conversion base format flag to 10.
sr<<hex
sr>>hex
These set the conversion base format flag to 16.
sr<<oct
sr>>oct
These set the conversion base format flag to 8.
Copyright 1994 Novell, Inc. Page 10
ios(3C++) ios(3C++)
sr>>ws
Extracts whitespace characters. See istream(3C++).
sr<<endl
Ends a line by inserting a newline character and
flushing. See ostream(3C++).
sr<<ends
Ends a string by inserting a null (0) character. See
ostream(3C++).
sr<<flush
Flushes outs. See ostream(3C++).
Several parameterized manipulators that operate on ios objects
are described in manip(3C++): setw, setfill, setprecision,
setiosflags, and resetiosflags.
The streambuf associated with an ios may be manipulated by
other methods than through the ios. For example, characters
may be stored in a queuelike streambuf through an ostream
while they are being fetched through an istream. Or for
efficiency some part of a program may choose to do streambuf
operations directly rather than through the ios. In most
cases the program does not have to worry about this
possibility, because an ios never saves information about the
internal state of a streambuf. For example, if the streambuf
is repositioned between extraction operations the extraction
(input) will proceed normally.
NOTICES
The need for sync_with_stdio is a wart. The old stream
package did this as a default, but in the iostream package
unbuffered stdiobufs are too inefficient to be the default.
The stream package had a constructor that took a FILE*
argument. This is now replaced by stdiostream. It is not
declared even as an obsolete form to avoid having iostream.h
depend on stdio.h.
The old stream package allowed copying of streams. This is
disallowed by the iostream package. However, objects of type
istream_withassign, ostream_withassign, and
iostream_withassign can be assigned to. Old code using
copying can usually be rewritten to use pointers or these
classes. (The standard streams cin, cout, cerr, and clog are
Copyright 1994 Novell, Inc. Page 11
ios(3C++) ios(3C++)
members of ``withassign'' classes, so they can be assigned to,
as in cin = inputfstream.)
REFERENCES
iostream(3C++), streambuf_pub(3C++), istream(3C++),
ostream(3C++), manip(3C++).
Copyright 1994 Novell, Inc. Page 12