ios(3C++)

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();
   	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.
-- 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()).
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 ) ...

Formatting

An ios has a formatstate 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 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 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 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 (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 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.
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 members of ``withassign'' classes, so they can be assigned to, as in cin = inputfstream.)

References

iostream(3C++), istream(3C++), manip(3C++), ostream(3C++), streambuf_pub(3C++)