13.39 <ostream>

The <ostream> header declares the output stream class template, specializations, and 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 9 for general information about I/O.

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.

See Also

ostream class, wostream class, iostream in <istream>

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 destroyed 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:

if ((os.flags(  ) & ios_base::unitbuf) && !uncaught_exception(  ))
  os.flush(  );

See Also

basic_ostream class template, basic_ios in <ios>

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

std::cout << "Hello, world." << std::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 the basic_ios class template (in <ios>) for information about tied streams and the ios_base class (also in <ios>) for information about unit buffering.

See Also

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

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 (defined by charT( )) to os to mark the end of a string. Typically, ends is used only when writing to a character array stream, that is, ostrstream:

std::ostrstream out1;
out1 << "Hi" << std::ends; // out1.str(  ) has length 2.

See Also

<strstream>

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:

std::cout << "This is important!" << std::flush;

See Also

basic_ostream class template

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

The << operator 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, and 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, basic_ostream::sentry class

typedef basic_ostream<char> ostream;

The ostream class specializes basic_ostream for the char type.

See Also

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

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 in <istream>