<ostream>
// DECLARATIONS class ostream; // INSERTERS ostream& operator<<(ostream& os, const char *s); ostream& operator<<(ostream& os, char c); ostream& operator<<(ostream& os, const signed char *s); ostream& operator<<(ostream& os, signed char c); ostream& operator<<(ostream& os, const unsigned char *s); ostream& operator<<(ostream& os, unsigned char c); // MANIPULATORS ostream& endl(ostream& os); ostream& ends(ostream& os); ostream& flush(ostream& os); // 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<<
· opfx
· osfx
· put
· seekp
· sentry
· tellp
· write
class ostream : public ios { public: explicit ostream(streambuf *sb); class sentry; virtual ~ostream(); bool opfx(); void osfx(); ostream& operator<<( ostream& (*pf)(ostream&)); ostream& operator<<( ios_base;& (*pf)(ios_base&)); ostream& operator<<( ios& (*pf)(ios&)); ostream& operator<<( streambuf *sb); ostream& operator<<(bool n); ostream& operator<<(short n); ostream& operator<<(unsigned short n); ostream& operator<<(int n); ostream& operator<<(unsigned int n); ostream& operator<<(long n); ostream& operator<<(unsigned long n); ostream& operator<<(float n); ostream& operator<<(double n); ostream& operator<<(long double n); ostream& operator<<(const void *n); ostream& put(char_type c); ostream& write(char_type *s, streamsize n); 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 (...) {if (exceptions() & badbit) throw; setstate(badbit); }} width(0); // except for operator<<(E) 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 (...) {if (rdstate() & badbit) throw; setstate(badbit); }} setstate(state); return (*this);
Both groups of functions call
setstate(badbit)
if they encounter a failure while inserting elements.
An object of class istream
stores only
a public base object of class
ios
ostream::ostream
explicit ostream(streambuf *sb);
The constructor initializes the base class by calling
init(sb)
.
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& (*pf)(ostream&)); ostream& operator<<( ios_base& (*pf)(ios_base&)); ostream& operator<<( ios& (*pf)(ios&)); ostream& operator<<( streambuf *sb); ostream& operator<<(bool n); ostream& operator<<(short n); ostream& operator<<(unsigned short n); ostream& operator<<(int n); ostream& operator<<(unsigned int n); ostream& operator<<(long n); ostream& operator<<(unsigned long n); ostream& operator<<(float n); ostream& operator<<(double n); ostream& operator<<(long double n); ostream& operator<<(const void *n);
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 *sb);
extracts elements from sb
,
if sb
is not a null pointer, and inserts them.
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 n);
converts n
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 n); ostream& operator<<(unsigned short n); ostream& operator<<(int n); ostream& operator<<(unsigned int n); ostream& operator<<(long n); ostream& operator<<(unsigned long n); ostream& operator<<(const void *n);
each convert n
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)n
.flags() & ios_base::basefield ==
ios_base::hex
, the
conversion specification is lx
and the converted value is
(unsigned long)n
.ld
and the converted value is (long)n
.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 n); ostream& operator<<(double n); ostream& operator<<(long double n);
each converts n
to a
floating-point output field
and inserts 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 n
has type double, the function prepends l
to the conversion specification. If n
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::opfx
bool opfx();
If good()
is true, and
tie()
is not
a null pointer, the member function calls
tie->flush()
.
It returns good()
.
You should not call opfx
directly.
It is called as needed by an object of class
sentry
.
ostream::osfx
void osfx();
If flags() &
unitbuf
is nonzero,
the member function calls
flush()
.
You should not call osfx
directly.
It is called as needed by an object of class
sentry
.
ostream::put
ostream& put(char_type c);
The unformatted output function
inserts the element c
. 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
rdbuf()->
pubseekpos(pos)
.
If fail()
is false, the second function calls
rdbuf()->
pubseekoff(off,
way)
. Both functions return *this
.
ostream::sentry
class sentry { public: explicit sentry(ostream& os); operator bool() const; private: sentry(const sentry&); // not defined sentry& operator=(const sentry&); // not defined };
The nested class describes an object whose declaration structures the
formatted output functions
and the
unformatted output functions.
The constructor effectively calls
os.opfx()
and
stores the return value. operator bool()
delivers this
return value. The destructor effectively calls
os.osfx()
.
ostream::tellp
pos_type tellp();
If fail()
is false,
the member function returns
rdbuf()->
pubseekoff(0,
cur,
in)
.
Otherwise, it returns
streampos(-1)
.
ostream::write
ostream& write(const char_type *s, streamsize n);
The unformatted output function
inserts the sequence of n
elements
beginning at s
.
endl
ostream endl(ostream& os);
The manipulator calls
os.put(os.
widen('\n'))
,
then calls
os.flush()
.
It returns os
.
ends
ostream& ends(ostream& os);
The manipulator calls
os.put(E('\0'))
.
It returns os
.
flush
ostream& flush(ostream& os);
The manipulator calls
os.flush()
.
It returns os
.
operator<<
ostream& operator<<(ostream& os, const char *s); ostream& operator<<(ostream& os, char c); ostream& operator<<(ostream& os, const signed char *s); ostream& operator<<(ostream& os, signed char c); ostream& operator<<(ostream& os, const unsigned char *s); ostream& operator<<(ostream& os, unsigned char c);
The function:
ostream& operator<<(ostream& os, const char *s);
is a
formatted output functions
that determines the length n =
traits_type::length(s)
of the sequence beginning at s
, and inserts the sequence. If
n < os.width()
,
then the function also inserts a repetition of os.width() - n
fill characters.
The repetition precedes the sequence if
(os.flags() &
adjustfield !=
left
.
Otherwise, the repetition follows the sequence.
The function returns os
.
The function:
ostream& operator<<(ostream& os, char c);
inserts the element c
. If
1 < os.width()
,
then the function also inserts a repetition of os.width() - 1
fill characters.
The repetition precedes the sequence if
(os.flags() &
adjustfield !=
left
.
Otherwise, the repetition follows the sequence.
It returns os
.
The function:
ostream& operator<<(ostream& os, const signed char *s);
returns os << (const char *)s
.
The function:
ostream& operator<<(ostream& os, signed char c);
returns os << (char)c
.
The function:
ostream& operator<<(ostream& os, const unsigned char *s);
returns os << (const char *)s
.
The function:
ostream& operator<<(ostream& os, unsigned char c);
returns os << (char)c
.
See also the Table of Contents and the Index.
Copyright © 1992-1996 by P.J. Plauger. All rights reserved.