Name

basic_ostream class template — Base class for output streams

Synopsis

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.

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.