OSTREAM(3C++) OSTREAM(3C++)
NAMEostream - formatted and unformatted output
SYNOPSIS
#include <iostream.h>
typedef long streamoff, streampos;
class ios {
public:
enum seek_dir { beg, cur, end };
enum open_mode { in, out, ate, app, trunc, nocreate, noreplace } ;
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 };
// and lots of other stuff, see ios(3C++) ...
} ;
class ostream : public ios {
public:
ostream(streambuf*);
ostream& flush();
int opfx();
ostream& put(char);
ostream& seekp(streampos);
ostream& seekp(streamoff, seek_dir);
streampos tellp();
ostream& write(const char* ptr, int n);
ostream& write(const unsigned char* ptr, int n);
ostream& operator<<(const char*);
ostream& operator<<(char);
ostream& operator<<(short);
ostream& operator<<(int);
ostream& operator<<(long);
ostream& operator<<(float);
ostream& operator<<(double);
ostream& operator<<(unsigned char);
ostream& operator<<(unsigned short);
ostream& operator<<(unsigned int);
ostream& operator<<(unsigned long);
ostream& operator<<(void*);
ostream& operator<<(streambuf*);
ostream& operator<<(ostream& (*)(ostream&));
ostream& operator<<(ios& (*)(ios&));
};
class ostream_withassign {
ostream_withassign();
istream& operator=(istream&);
istream& operator=(streambuf*);
Page 1
OSTREAM(3C++) OSTREAM(3C++)
};
extern ostream_withassign cout;
extern ostream_withassign cerr;
extern ostream_withassign clog;
ostream& endl(ostream&) ;
ostream& ends(ostream&) ;
ostream& flush(ostream&) ;
ios& dec(ios&) ;
ios& hex(ios&) ;
ios& oct(ios&) ;
DESCRIPTION
ostreams support insertion (storing) into a streambuf. These are
commonly referred to as output operations. The ostream member functions
and related functions are described below.
In the following descriptions, assume:
- outs is an ostream.
- outswa is an ostream_withassign.
- outsp is an ostream*.
- c is a char.
- ptr is a char* or unsigned char*.
- sb is a streambuf*
- i and n are ints.
- pos is a streampos.
- off is a streamoff.
- dir is a seek_dir.
- manip is a function with type ostream& (*)(ostream&).
Constructors and assignment:
ostream(sb)
Initializes ios state variables and associates buffer sb with
the ostream.
ostream_withassign()
Does no initialization. This allows a file static variable of
this type (cout, for example) to be used before it is
constructed, provided it is assigned to first.
outswa=sb
Associates sb with swa and initializes the entire state of
outswa.
inswa=ins
Associates ins->rdbuf() with swa and initializes the entire
state of outswa.
Output prefix function:
Page 2
OSTREAM(3C++) OSTREAM(3C++)
i=outs.opfx()
If outs's error state is nonzero, returns immediately. If
outs.tie() is non-null, it is flushed. Returns non-zero except
when outs's error state is nonzero.
Output suffix function:
osfx()
Performs ``suffix'' actions before returning from inserters.
If ios::unitbuf is set, osfx() flushes the ostream. If
ios::stdio is set, osfx() flushes stdout and stderr.
osfx() is called by all predefined inserters, and should be called
by user-defined inserters as well, after any direct manipulation of
the streambuf. It is not called by the binary output functions.
Formatted output functions (inserters):
outs<<x
First calls outs.opfx() and if that returns 0, does nothing.
Otherwise inserts a sequence of characters representing x into
outs.rdbuf(). Errors are indicated by setting the error state
of outs. outs is always returned.
x is converted into a sequence of characters (its
representation) according to rules that depend on x's type and
outs's format state flags and variables (see ios(3C++)).
Inserters are defined for the following types, with conversion
rules as described below:
char*
The representation is the sequence of characters up to
(but not including) the terminating null of the string x
points at.
any integral type except char and unsigned char
If x is positive the representation contains a sequence of
decimal, octal, or hexadecimal digits with no leading
zeros according to whether ios::dec, ios::oct, or
ios::hex, respectively, is set in ios's format flags. If
none of those flags are set, conversion defaults to
decimal. If x is zero, the representation is a single
zero character(0). If x is negative, decimal conversion
converts it to a minus sign (-) followed by decimal
digits. If x is positive and ios::showpos is set, decimal
conversion converts it to a plus sign (+) followed by
decimal digits. The other conversions treat all values as
unsigned. If ios::showbase is set in ios's format flags,
the hexadecimal representation contains 0x before the
hexadecimal digits, or 0X if ios::uppercase is set. If
ios::showbase is set, the octal representation contains a
leading 0.
Page 3
OSTREAM(3C++) OSTREAM(3C++)
void*
Pointers are converted to integral values and then
converted to hexadecimal numbers as if ios::showbase were
set.
float, double
The arguments are converted according to the current
values of outs.precision(), outs.width() and outs's format
flags ios::scientific, ios::fixed, and ios::uppercase.
(See ios(3C++).) The default value for outs.precision()
is 6. If neither ios::scientific nor ios::fixed is set,
either fixed or scientific notation is chosen for the
representation, depending on the value of x.
char, unsigned char
No special conversion is necessary.
After the representation is determined, padding occurs. If
outs.width() is greater than 0 and the representation contains
fewer than outs.width() characters, then enough outs.fill()
characters are added to bring the total number of characters to
ios.width(). If ios::left is set in ios's format flags, the
sequence is left-adjusted, that is, characters are added after
the characters determined above. If ios::right is set, the
padding is added before the characters determined above. If
ios::internal is set, the padding is added after any leading
sign or base indication and before the characters that
represent the value. ios.width() is reset to 0, but all other
format variables are unchanged. The resulting sequence
(padding plus representation) is inserted into outs.rdbuf().
outs<<sb
If outs.opfx() returns non-zero, the sequence of characters
that can be fetched from sb are inserted into outs.rdbuf().
Insertion stops when no more characters can be fetched from sb.
No padding is performed. Always returns outs.
Unformatted output functions:
outsp=&outs.put(c)
Inserts c into outs.rdbuf(). Sets the error state if the
insertion fails.
outsp=&outs.write(s,n)
Inserts the n characters starting at s into outs.rdbuf().
These characters may include zeros (i.e., s need not be a null
terminated string).
Other member functions:
outsp=&outs.flush()
Storing characters into a streambuf does not always cause them
to be consumed (e.g., written to the external file)
immediately. flush() causes any characters that may have been
Page 4
OSTREAM(3C++) OSTREAM(3C++)
stored but not yet consumed to be consumed by calling
outs.rdbuf()->sync.
outs<<manip
Equivalent to manip(outs). Syntactically this looks like an
insertion operation, but semantically it does an arbitrary
operation rather than converting manip to a sequence of
characters as do the insertion operators. Predefined
manipulators are described below.
Positioning functions:
outsp=&ins.seekp(off,dir)
Repositions outs.rdbuf()'s put pointer. See sbuf.pub(3C++) for
a discussion of positioning.
outsp=&outs.seekp(pos)
Repositions outs.rdbuf()'s put pointer. See sbuf.pub(3C++) for
a discussion of positioning.
pos=outs.tellp()
The current position of outs.rdbuf()'s put pointer. See
sbuf.pub(3C++) for a discussion of positioning.
Manipulators:
outs<<endl
Ends a line by inserting a newline character and flushing.
outs<<ends
Ends a string by inserting a null (0) character.
outs<<flush
Flushes outs.
outs<<dec
Sets the conversion base format flag to 10. See ios(3C++).
outs<<hex
Sets the conversion base format flag to 16. See ios(3C++).
outs<<oct
Sets the conversion base format flag to 8. See ios(3C++).
SEE ALSO
ios(3C++), sbuf.pub(3C++), manip(3C++)
Page 5
