<ostream>
// DECLARATIONS class ostream; // INSERTERS ostream& operator<<(ostream& ostr, const char *str); ostream& operator<<(ostream& ostr, char ch); ostream& operator<<(ostream& ostr, const signed char *str); ostream& operator<<(ostream& ostr, signed char ch); ostream& operator<<(ostream& ostr, const unsigned char *str); ostream& operator<<(ostream& ostr, unsigned char ch); // MANIPULATORS ostream& endl(ostream& ostr); ostream& ends(ostream& ostr); ostream& flush(ostream& ostr); // END OF DECLARATIONS
Include the iostreams
standard header <ostream>
to define
class ostream
,
which mediates insertions for the iostreams.
The header also defines several related
manipulators.
(This header is typically included for you by another
of the iostreams headers. You seldom have occasion to include it
directly.)
ostream
ostream
· flush
· operator<<
· put
· seekp
· sentry
· tellp
· write
class ostream : public ios { public: explicit ostream(streambuf *strbuf); class sentry; virtual ~ostream(); ostream& operator<<( ostream& (*pfn)(ostream&)); ostream& operator<<( ios_base;& (*pfn)(ios_base&)); ostream& operator<<( ios& (*pfn)(ios&)); ostream& operator<<( streambuf *strbuf); ostream& operator<<(bool val); ostream& operator<<(short val); ostream& operator<<(unsigned short val); ostream& operator<<(int val); ostream& operator<<(unsigned int val); ostream& operator<<(long val); ostream& operator<<(unsigned long val); ostream& operator<<(float val); ostream& operator<<(double val); ostream& operator<<(long double val); ostream& operator<<(const void *val); ostream& put(char_type ch); ostream& write(char_type *str, streamsize count); ostream& flush(); pos_type tellp(); ostream& seekp(pos_type pos); ostream& seekp(off_type off, ios_base::seek_dir way); };
The class describes an object that controls
insertion of elements and encoded objects into a
stream buffer
with elements of type char, also known as
char_type
, whose
character traits are determined by the
class char_traits
,
also known as
traits_type
.
Most of the member functions that overload
operator<<
are formatted output functions.
They follow the pattern:
iostate state = goodbit; const sentry ok(*this); if (ok) {try {<convert and insert elements accumulate flags in state> } catch (...) {try {setstate(badbit); } catch (...) {} if ((exceptions() & badbit) != 0) throw; }} width(0); // except for operator<<(Elem) setstate(state); return (*this);
Two other member functions are unformatted output functions. They follow the pattern:
iostate state = goodbit; const sentry ok(*this); if (!ok) state |= badbit; else {try {<obtain and insert elements accumulate flags in state> } catch (...) {try {setstate(badbit); } catch (...) {} if ((exceptions() & badbit) != 0) throw; }} setstate(state); return (*this);
Both groups of functions call
setstate(badbit)
if they encounter a failure while inserting elements.
An object of class ostream
stores only
a public base object of class
ios
ostream::ostream
explicit ostream(streambuf *strbuf);
The constructor initializes the base class by calling
init(strbuf)
.
ostream::flush
ostream& flush();
If rdbuf()
is
not a null pointer, the function calls
rdbuf()->pubsync()
.
If that returns -1, the function calls
setstate(badbit)
.
It returns *this
.
ostream::operator<<
ostream& operator<<( ostream& (*pfn)(ostream&)); ostream& operator<<( ios_base& (*pfn)(ios_base&)); ostream& operator<<( ios& (*pfn)(ios&)); ostream& operator<<( streambuf *strbuf); ostream& operator<<(bool val); ostream& operator<<(short val); ostream& operator<<(unsigned short val); ostream& operator<<(int val); ostream& operator<<(unsigned int val); ostream& operator<<(long val); ostream& operator<<(unsigned long val); ostream& operator<<(float val); ostream& operator<<(double val); ostream& operator<<(long double val); ostream& operator<<(const void *val);
The first member function ensures that an expression of the
form ostr << endl
calls
endl(ostr)
, then returns *this
.
The second and third functions ensure that other
manipulators,
such as hex
behave
similarly. The remaining functions are all
formatted output functions.
The function:
ostream& operator<<( streambuf *strbuf);
extracts elements from strbuf
,
if strbuf
is not a null pointer, and inserts them.
If strbuf
is a null pointer, the function calls
setstate(badbit)
.
Otherwise, extraction stops on end-of-file,
or if an extraction throws an exception (which is rethrown).
It also stops, without extracting the element in question,
if an insertion fails. If the function inserts no elements, or
if an extraction throws an exception, the function calls
setstate(failbit)
.
In any case, the function returns *this
.
All the remaining functions generate an output field and insert it.
The output output field is generated by the same rules used by the
print functions
for generating a series of char elements to a file.
Where a print function pads a field with either spaces or the digit
0
, however, the function instead uses
fill
.
The equivalent
print conversion
specification is determined as described for each function below.
Padding occurs only if
the minimum number of elements N
required to
specify the output field is less than
width()
.
Such padding consists of a sequence of N - width()
copies of
fill()
.
Padding then occurs as follows:
flags() &
ios_base::adjustfield ==
ios_base::left
,
the flag -
is prepended to the conversion specification.
(Padding occurs after the generated text.)
flags() & ios_base::adjustfield ==
ios_base::internal
,
the flag 0
is prepended. (For a numeric output field,
padding occurs where the print functions pad with 0
.)The function:
ostream& operator<<(bool val);
converts val
to a
boolean output field
and inserts it as an array of char, with
a conversion specifier of s
.
A boolean output field takes one of two forms.
If flags() &
ios_base::boolalpha
is false, the generated sequence is either 0
(for false)
or 1
(for true).
Otherwise, the generated sequence is either
false
(for false), or
true
(for true). The
function then calls width(0)
to reset the
field width to zero.
The function returns *this
.
The functions:
ostream& operator<<(short val); ostream& operator<<(unsigned short val); ostream& operator<<(int val); ostream& operator<<(unsigned int val); ostream& operator<<(long val); ostream& operator<<(unsigned long val); ostream& operator<<(const void *val);
each convert val
to an
integer output field
and inserts it. The equivalent
print conversion
specification is determined as follows:
flags() &
ios_base::basefield ==
ios_base::oct
, the
conversion specification is lo
and the converted value is
(long)val
.flags() & ios_base::basefield ==
ios_base::hex
, the
conversion specification is lx
and the converted value is
(unsigned long)val
.ld
and the converted value is (long)val
.If width()
is nonzero, a field width of this value is prepended. The
function then calls width(0)
to reset the
field width to zero.
Finally:
flags() &
ios_base::showpos
is nonzero, the flag +
is prepended to the conversion
specification.flags() &
ios_base::showbase
is nonzero, the flag #
is prepended to the conversion
specification.The function returns *this
.
The functions:
ostream& operator<<(float val); ostream& operator<<(double val); ostream& operator<<(long double val);
each convert val
to a
floating-point output field
and insert it.
A period (.
) separates the integer digits from the
fraction digits.
The equivalent print conversion specification is determined as follows:
flags() &
ios_base::floatfield ==
ios_base::fixed
, the
conversion specification is f
.flags() & ios_base::floatfield ==
ios_base::scientific
, the
conversion specification is e
.
If flags() &
ios_base::uppercase
is nonzero, e
is replaced with E
.g
.
If flags() & ios_base::uppercase
is nonzero, g
is replaced with G
.If val
has type double, the function prepends l
to the conversion specification. If val
has type long double,
it prepends L
to the conversion specification.
If flags() & ios_base::fixed
is nonzero, or if
precision()
is greater than zero, a precision with the value
precision()
is prepended to the conversion specification.
Any padding behaves the same
as for an integer output field.
If width()
is nonzero, a field width of this value is prepended. The
function then calls width(0)
to reset the
field width to zero. Finally:
flags() &
ios_base::showpos
is nonzero, the flag +
is prepended to the conversion
specification.flags() &
ios_base::showpoint
is nonzero, the flag #
is prepended to the conversion
specification.ostream::put
ostream& put(char_type ch);
The unformatted output function
inserts the element ch
. It returns *this
.
ostream::seekp
ostream& seekp(pos_type pos); ostream& seekp(off_type off, ios_base::seek_dir way);
If fail()
is false,
the first member function calls
newpos = rdbuf()->
pubseekpos(pos,
out)
,
for some pos_type
temporary object newpos
.
If fail()
is false, the second function calls
newpos = rdbuf()->
pubseekoff(off, way,
out)
.
In either case, if (off_type)newpos == (off_type)(-1)
(the positioning operation fails) the function calls
istr.setstate(failbit)
.
Both functions return *this
.
ostream::sentry
class sentry { public: explicit sentry(ostream& ostr); operator bool() const; ~sentry(); private: sentry(const sentry&); // not defined sentry& operator=(const sentry&); // not defined bool status; };
The nested class describes an object whose declaration structures the
formatted output functions
and the
unformatted output functions.
If ostr.good()
is true, and
ostr.tie()
is not
a null pointer, the constructor calls
ostr.tie->flush()
.
The constructor then stores the value returned by ostr.good()
in status.
A later call to operator bool()
delivers this stored value.
If
flags() &
unitbuf
is nonzero,
the destructor calls
flush()
.
ostream::tellp
pos_type tellp();
If fail()
is false,
the member function returns
rdbuf()->
pubseekoff(0,
cur,
in)
.
Otherwise, it returns pos_type(-1)
.
ostream::write
ostream& write(const char_type *str, streamsize count);
The unformatted output function
inserts the sequence of count
elements
beginning at str
.
endl
ostream endl(ostream& ostr);
The manipulator calls
ostr.put(ostr.
widen('\n'))
,
then calls
ostr.flush()
.
It returns ostr
.
ends
ostream& ends(ostream& ostr);
The manipulator calls
ostr.put(Elem('\0'))
.
It returns ostr
.
flush
ostream& flush(ostream& ostr);
The manipulator calls
ostr.flush()
.
It returns ostr
.
operator<<
ostream& operator<<(ostream& ostr, const char *str); ostream& operator<<(ostream& ostr, char ch); ostream& operator<<(ostream& ostr, const signed char *str); ostream& operator<<(ostream& ostr, signed char ch); ostream& operator<<(ostream& ostr, const unsigned char *str); ostream& operator<<(ostream& ostr, unsigned char ch);
All of these functions are formatted output functions. The function:
ostream& operator<<(ostream& ostr, const char *str);
determines the length N =
traits_type::length(str)
of the sequence beginning at str
, and inserts the sequence. If
N < ostr.width()
,
then the function also inserts a repetition of ostr.width() - N
fill characters.
The repetition precedes the sequence if
(ostr.flags() &
adjustfield !=
left
.
Otherwise, the repetition follows the sequence.
The function returns ostr
.
The function:
ostream& operator<<(ostream& ostr, char ch);
inserts the element ch
. If
1 < ostr.width()
,
then the function also inserts a repetition of ostr.width() - 1
fill characters.
The repetition precedes the sequence if
(ostr.flags() &
adjustfield !=
left
.
Otherwise, the repetition follows the sequence.
It returns ostr
.
The function:
ostream& operator<<(ostream& ostr, const signed char *str);
returns ostr << (const char *)str
.
The function:
ostream& operator<<(ostream& ostr, signed char ch);
returns ostr << (char)ch
.
The function:
ostream& operator<<(ostream& ostr, const unsigned char *str);
returns ostr << (const char *)str
.
The function:
ostream& operator<<(ostream& ostr, unsigned char ch);
returns ostr << (char)ch
.
See also the Table of Contents and the Index.
Copyright © 1992-2002 by P.J. Plauger. All rights reserved.