Draft 2002-08-19

<ostream>

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 <string> for information about the char_traits template. Refer to Chapter 10 for general information about I/O.

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<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)
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 the buffer is flushed.
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)
Seeks to a new position in the stream. 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)
Format a value and write the formatted characters to the output stream. These functions start by creating a sentry object, then use the 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)
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:
If no characters are written, failbit is set.

See Also

ostream class, wostream class, iostream in <istream>

basic_ostream::sentry class

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();

See Also

basic_ostream class template, basic_ios in <ios>

endl function template

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.

See Also

basic_ios::tie in <ios>, ios_base::fmtflags in <ios>

ends function template

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

See Also

ostringstream in <sstream>

flush function template

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;

See Also

basic_ostream function template

operator<< 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.

See Also

basic_ostream class template

ostream class

Output stream

typedef basic_ostream<char> ostream;

The ostream class specializes basic_ostream for the char type.

See Also

basic_ostream class template, wostream class, iostream class in <istream>

wostream class

Wide output stream

typedef basic_ostream<wchar_t> wostream;

The wostream class specializes basic_ostream for the wchar_t type.

See Also

basic_ostream class template, ostream class, wiostream class in <istream>