basic_ostream class template — Base class for output streams
template <class charT, class traits = char_traits<charT> > class basic_ostream : virtual public basic_ios<charT,traits> { public: // Types (inherited from basic_ios) typedef charT char_type; typedef typename traits::int_type int_type; typedef typename traits::pos_type pos_type; typedef typename traits::off_type off_type; typedef traits traits_type; explicit basic_ostream(basic_streambuf<charT,traits>* sb); virtual ~basic_ostream( ); class sentry; // Formatted output basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>& (*pf)(basic_ostream<charT,traits>&)); basic_ostream<charT,traits>& operator<<(basic_ios<charT,traits>& (*pf)(basic_ios<charT,traits>&)); basic_ostream<charT,traits>& operator<<(ios_base&(*pf)(ios_base&)); basic_ostream<charT,traits>& operator<<(bool n); basic_ostream<charT,traits>& operator<<(short n); basic_ostream<charT,traits>& operator<<(unsigned short n); basic_ostream<charT,traits>& operator<<(int n); basic_ostream<charT,traits>& operator<<(unsigned int n); basic_ostream<charT,traits>& operator<<(long n); basic_ostream<charT,traits>& operator<<(unsigned long n); basic_ostream<charT,traits>& operator<<(float f); basic_ostream<charT,traits>& operator<<(double f); basic_ostream<charT,traits>& operator<<(long double f); basic_ostream<charT,traits>& operator<<(const void* p); basic_ostream<charT,traits>& operator<< (basic_streambuf<char_type,traits>* sb); // Unformatted output basic_ostream<charT,traits>& put(char_type c); basic_ostream<charT,traits>& write(const char_type* s, streamsize n); basic_ostream<charT,traits>& flush( ); pos_type tellp( ); basic_ostream<charT,traits>& seekp(pos_type); basic_ostream<charT,traits>& seekp(off_type, ios_base::seekdir); };
The basic_ostream
class
template is the base for all output streams. It declares members for
writing to streams and for managing streams. The act of writing to a
stream is also known as inserting to the
stream.
All writes go through a stream buffer, which provides
low-level access to the stream data. (See the sputc
function for basic_streambuf
in the <streambuf>
header.) If the stream
buffer object throws an exception, the stream sets badbit
.
Before performing an output operation (e.g., operator<<
, put
, or write
), a stream constructs a sentry
object. If the sentry
evaluates to true
, the write operation continues. If
the write throws an exception, badbit
is set. The sentry
object is destroyed before the
output function returns. See basic_ostream::sentry
later in this
section for more information.
When an output operation throws an exception, the stream sets
badbit
. If badbit
is set in the exceptions( )
mask, the stream does not
throw ios_base::failure
, but
instead rethrows the original exception.
The following are the basic_ostream
member functions:
explicit
basic_ostream
(basic_streambuf<char_type,traits>*
sb)
Constructs a basic_ostream
object and then
initializes it by calling init(sb)
.
virtual
~basic_ostream
( )
Destroys the basic_ostream
object without calling
any functions of the stream buffer. Derived classes that might
have buffered, unflushed data must take appropriate action to
ensure that the buffer is flushed before the stream object is
destroyed.
basic_ostream<charT,traits>&
flush
( )
Flushes the output buffer. If rdbuf( )
is not null, flush
calls rdbuf( )->pubsync( )
. If pubsync
returns -1
, flush
sets badbit
. The return value is *this
.
basic_ostream<charT,traits>&
put
(char_type
c)
Writes a single character c
. If the write fails, put
sets badbit
. The return value is *this
.
basic_ostream<charT,traits>&
seekp
(pos_type
pos)
, basic_ostream<charT,traits>&
seekp
(off_type
off, ios_base::seekdir
dir)
Tries to seek to a new position in the stream. The first
form specifies the position explicitly; the second form
specifies the new position as an offset from a known position
(start-of-file, current position, or end-of-file). If fail( )
is false
, seekp
calls rdbuf( )->pubseekoff(pos)
or
rdbuf( )->pubseekoff(off,
dir)
. If fail( )
is true
, seekp
does nothing. The return value
is *this
.
pos_type
tellp
( )
Returns the current position in the stream. If fail( )
is true
, the return value is pos_type(-1)
; otherwise, the return
value is rdbuf(
)->pubseekoff(0,ios_base::cur,ios_base::out)
.
basic_ostream<charT,traits>&
write
(const
char_type*
s
, streamsize
n)
Writes n
characters
from s
. If the output fails
after any character, write
sets badbit
and stops
writing. The return value is *this
.
basic_ostream<charT,traits>&
operator<<
(basic_ostream<charT,traits>&
(*pf)(basic_ostream<charT,traits>&))
Calls pf(*this)
and
returns *this
. See endl
later in this section for an
example of a manipulator that uses this operator.
basic_ostream<charT,traits>&
operator<<
(basic_ios<charT,traits>&
(*pf)(basic_ios<charT,traits>&))
, basic_ostream<charT,traits>&
operator<<
(ios_base&
(*pf)(ios_base&))
Calls pf(*this)
and
returns *this
. See the
dec
function in <ios>
for an example of a
manipulator that uses this operator.
basic_ostream<charT,traits>&
operator<<
(bool n)
, basic_ostream<charT,traits>&
operator<<
(short n)
, basic_ostream<charT,traits>&
operator<<
(unsigned short n)
, basic_ostream<charT,traits>&
operator<<
(int n)
, basic_ostream<charT,traits>&
operator<<
(unsigned int n)
, basic_ostream<charT,traits>&
operator<<
(long n)
, basic_ostream<charT,traits>&
operator<<
(unsigned long n)
, basic_ostream<charT,traits>&
operator<<
(float f)
, basic_ostream<charT,traits>&
operator<<
(double f)
, basic_ostream<charT,traits>&
operator<<
(long double f)
, basic_ostream<charT,traits>&
operator<<
(const void* p)
Formats a value and writes the formatted characters to
the output stream. These functions start by creating a
sentry
object; they then
use the num_put
facet of
the stream's imbued locale as shown in Example 13-33. If the
formatting fails, failbit
is set. If an exception is thrown, badbit
is set. See the <locale>
header for
information about num_put
and locales.
Example 13-33. Using the num_put facet to format output
typedef std::num_put<char_type, std::ostreambuf_iterator<char_type, traits_type> > numput; std::ostreambuf_iterator<char_type, traits_type> iter = std::use_facet<numput>(getloc( )).(*this,*this,fill( ),val); if (iter.failed( )) setstate(ios_base::badbit);
basic_ostream<charT,traits>&
operator<<
(basic_streambuf<char_type,traits>*
sb)
Writes characters from the stream buffer sb
. If sb
is null, badbit
is set. Otherwise, characters
are read from sb
and
written to *this
until one
of the following happens:
The end-of-file is reached on sb
Writing fails (badbit
is set)
An exception is thrown when reading from sb
(failbit
is set)
If no characters are written, failbit
is set.