ostream(3C++) ostream(3C++)
NAME
ostream - 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<<(long 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&));
Copyright 1994 Novell, Inc. Page 1
ostream(3C++) ostream(3C++)
ostream& operator<<(ios& (*)(ios&));
};
class ostream_withassign : public ostream {
ostream_withassign();
istream& operator=(istream&);
istream& operator=(streambuf*);
};
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
Copyright 1994 Novell, Inc. Page 2
ostream(3C++) ostream(3C++)
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:
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.
Copyright 1994 Novell, Inc. Page 3
ostream(3C++) ostream(3C++)
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.
void* Pointers are converted to integral values and then
converted to hexadecimal numbers as if
ios::showbase were set.
float, double, long 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.
Copyright 1994 Novell, Inc. Page 4
ostream(3C++) ostream(3C++)
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 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
streambuf_pub(3C++) for a discussion of positioning.
Copyright 1994 Novell, Inc. Page 5
ostream(3C++) ostream(3C++)
outsp=&outs.seekp(pos)
Repositions outs.rdbuf()'s put pointer. See
streambuf_pub(3C++) for a discussion of positioning.
pos=outs.tellp()
The current position of outs.rdbuf()'s put pointer. See
streambuf_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++).
REFERENCES
ios(3C++), streambuf_pub(3C++), manip(3C++)
Copyright 1994 Novell, Inc. Page 6