The <ostream>
header declares the output stream classes manipulators.
See <fstream>
for derived classes that write to files and <sstream>
for derived classes that write to strings. See <ios>
for the base class declarations. See <strin
g
>
for information about the char_traits
template. Refer to Chapter 10 for general information about I/O.
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<char_type,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 the 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()
), the stream constructs a sentry
object. if the sentry returns true, the writes operation continues. If the write throws an exception, badbit
is set. The sentry object is destructed 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.
Following are the basic_ostream
member functions:
explicit
basic_ostream
(basic_streambuf<char_type,traits>*
sb)
basic_ostream
object and then initializes it by calling init(sb)
.virtual
~basic_ostream
()
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 the buffer is flushed.basic_ostream<charT,traits>&
flush
()
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)
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)
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
()
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)
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>&))
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>&))
operator<<
(ios_base& (*pf)(ios_base&))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)
num_put
facet of the stream's imbued locale as shown in Example 13-36. 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-36: 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)
sb
. If sb
is null, badbit
is set. Otherwise, characters are read from sb
and written to *this
until one of the following happens:sb
,badbit
is set)sb
(failbit
is set)failbit
is set.ostream class, wostream class, iostream in <istream>
Sentry class for output streams
template <class charT,class traits = char_traits<charT> > class basic_ostream<charT,traits>::sentry { public: explicit sentry(basic_ostream<charT,traits>& os); ~sentry(); operator bool() const; private: sentry(const sentry&); // not defined sentry& operator=(const sentry&); // not defined };
A basic_ostream
object constructs a temporary sentry
object prior to each output operation. The sentry object is destructed when the output operation finishes and the function returns. The sentry manages tied streams and unit-buffering.
The stream passes itself to the sentry's constructor. If stream.good()
is true, the sentry first flushes any tied stream. That is, if stream.tie()
is not null, the sentry calls stream.tie()->flush()
.
If sentry preparation fails, badbit
is set.
The sentry destructor flushes the buffer if the unitbuf
flag is on and the output function did not throw an exception. That is,
if ((os.flags()&ios_base::unitbuf) && !uncaught_exception()) os.flush();
basic_ostream class template, basic_ios in <ios>
Manipulator to write an end of line character
template <class charT, class traits> basic_ostream<charT,traits>& endl(basic_ostream<charT,traits>& os);
The endl
function template is a manipulator that writes a newline to os
and then calls os
.flush()
. For example:
std::cout << "Hello, world." << endl;
If you do not need to flush the output stream, do not use endl
; write a plain '\n'
character instead. If you feel you need to flush the output stream after finishing a line of output, consider using unit buffering for the stream, or if you need to flush the output prior to reading an input stream, you can tie the streams instead of using endl
.
basic_ios::tie in <ios>, ios_base::fmtflags in <ios>
Manipulator to write an end of string character
template <class charT, class traits> basic_ostream<charT,traits>& ends(basic_ostream<charT,traits>& os);
The ends
function template is a manipulator that writes a null character (end of string), that is, charT()
, to os
. You do not typically need to call ends
, even when writing to a string stream. Consider, for example, the following:
std::ostringstream out1, out2; out1 << "Hi" << ends; // out1.str() has three characters out2 << "Hi"; // out2.str() has two characters
ostringstream in <sstream>
Manipulator to flush output buffer
template <class charT, class traits> basic_ostream<charT,traits>& flush(basic_ostream<charT,traits>& os);
The flush
function template is a manipulator that calls os.flush
. For example,
std::cout << "This is important!" << flush;
basic_ostream function template
Character output operator
template<class charT, class traits> basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>& out, charT c); template<class charT, class traits> basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>& out, char c); template<class traits> basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>& out, char c); template<class traits> basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>& out, signed char c); template<class traits> basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>& out, unsigned char c); template<class charT, class traits> basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>& out, const charT* s); template<class charT, class traits> basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>& out, const char* s); template<class traits> basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>& out, const char* s); template<class traits> basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>& out, const signed char* s); template<class traits> basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>& out, const unsigned char* s);
Writes a single character c
or a character string s
to the output stream out
. As with other formatted output functions, a sentry object is created, the character or string is written with appropriate padding. Each character is converted to the stream's character type by calling widen. Finally, width(0)
is called.
basic_ostream class template
Output stream
typedef basic_ostream<char> ostream;
The ostream
class specializes basic_ostream
for the char
type.
basic_ostream class template, wostream class, iostream class in <istream>
Wide output stream
typedef basic_ostream<wchar_t> wostream;
The wostream
class specializes basic_ostream
for the wchar_t
type.
basic_ostream class template, ostream class, wiostream class in <istream>