ostream(C++std)

basic_ostream , endl , ends , flush , operator<< , ostream , wostream - defines the template class that performs insertions

Synopsis

   namespace std {
   template<class E, class T = char_traits<E> >
       class basic_ostream;
   typedef basic_ostream<char, char_traits<char> >
       ostream;
   typedef basic_ostream<wchar_t, char_traits<wchar_t> >
       wostream;

           // INSERTERS
   template<class E, class T>
       basic_ostream<E, T>&
           operator<<(basic_ostream<E, T>& os,
               const E *s);
   template<class E, class T>
       basic_ostream<E, T>&
           operator<<(basic_ostream<E, T>& os,
               E c);
   template<class E, class T>
       basic_ostream<E, T>&
           operator<<(basic_ostream<E, T>& os,
               const char *s);
   template<class E, class T>
       basic_ostream<E, T>&
           operator<<(basic_ostream<E, T>& os,
               char c);
   template<class T>
       basic_ostream<char, T>&
           operator<<(basic_ostream<char, T>& os,
               const char *s);
   template<class T>
       basic_ostream<char, T>&
           operator<<(basic_ostream<char, T>& os,
               char c);
   template<class T>
       basic_ostream<char, T>&
           operator<<(basic_ostream<char, T>& os,
               const signed char *s);
   template<class T>
       basic_ostream<char, T>&
           operator<<(basic_ostream<char, T>& os,
               signed char c);
   template<class T>
       basic_ostream<char, T>&
           operator<<(basic_ostream<char, T>& os,
               const unsigned char *s);
   template<class T>
       basic_ostream<char, T>&
           operator<<(basic_ostream<char, T>& os,
               unsigned char c);

           // MANIPULATORS
   template class<E, T>
       basic_ostream<E, T>&
           endl(basic_ostream<E, T>& os);
   template class<E, T>
       basic_ostream<E, T>&
           ends(basic_ostream<E, T>& os);
   template class<E, T>
       basic_ostream<E, T>&
           flush(basic_ostream<E, T>& os);
       };

Description

Include the iostreams standard header <ostream> to define template class basic_ostream, which mediates insertions for the iostreams. The header also defines several related manipulators. (This header is typically included for you by another of the iostreams headers. You seldom have occasion to include it directly.)

basic_ostream

basic_ostream , flush , operator<< , opfx , osfx , put , seekp , sentry , tellp , write

   template <class E, class T = char_traits<E> >
       class basic_ostream
           : virtual public basic_ios<E, T> {
   public:
       typedef typename basic_ios<E, T>::char_type char_type;
       typedef typename basic_ios<E, T>::traits_type traits_type;
       typedef typename basic_ios<E, T>::int_type int_type;
       typedef typename basic_ios<E, T>::pos_type pos_type;
       typedef typename basic_ios<E, T>::off_type off_type;
       explicit basic_ostream(basic_streambuf<E, T> *sb);
       class sentry;
       virtual ~ostream();
       bool opfx();
       void osfx();
       basic_ostream& operator<<(
           basic_ostream& (*pf)(basic_ostream&));
       basic_ostream& operator<<(
           ios_base;& (*pf)(ios_base&));
       basic_ostream& operator<<(
           basic_ios<E, T>& (*pf)(basic_ios<E, T>&));
       basic_ostream& operator<<(
           basic_streambuf<E, T> *sb);
       basic_ostream& operator<<(bool n);
       basic_ostream& operator<<(short n);
       basic_ostream& operator<<(unsigned short n);
       basic_ostream& operator<<(int n);
       basic_ostream& operator<<(unsigned int n);
       basic_ostream& operator<<(long n);
       basic_ostream& operator<<(unsigned long n);
       basic_ostream& operator<<(float n);
       basic_ostream& operator<<(double n);
       basic_ostream& operator<<(long double n);
       basic_ostream& operator<<(const void *n);
       basic_ostream& put(char_type c);
       basic_ostream& write(char_type *s, streamsize n);
       basic_ostream& flush();
       pos_type tellp();
       basic_ostream& seekp(pos_type pos);
       basic_ostream& seekp(off_type off,
           ios_base::seek_dir way);
       };

The template class describes an object that controls insertion of elements and enSTRONGd objects into a stream buffer with elements of type Eso known as char_typeose character traits are determined by the class T, also known as traits_type.

Most of the member functions that overload operator<< are formatted output functions. They follow the pattern:

       iostate state = goodbit;
       const sentry ok(*this);
       if (ok)
           {try
               {<convert and insert elements
               accumulate flags in state>}
           catch (...)
               {try
                   {setstate(badbit); }
   			catch (...)
   				{}
               if ((exceptions() & badbit) != 0)
                   throw; }}
       width(0);    // except for operator<<(E)
       setstate(state);
       return (*this);

Two other member functions are unformatted output functions. They follow the pattern:

       iostate state = goodbit;
       const sentry ok(*this);
       if (!ok)
           state |= badbit;
       else
           {try
               {<obtain and insert elements
               accumulate flags in state>}
           catch (...)
               {try
                   {setstate(badbit); }
   			catch (...)
   				{}
               if ((exceptions() & badbit) != 0)
                   throw; }}
       setstate(state);
       return (*this);

Both groups of functions call setstate(badbit) if they encounter a failure while inserting elements.

An object of class basic_istream<E, T> stores only a virtual public base object of class basic_ios<E, T>

basic_ostream::basic_ostream

   explicit basic_ostream(basic_streambuf<E, T> *sb);

The constructor initializes the base class by calling init(sb).

basic_ostream::flush

   basic_ostream& flush();

If rdbuf() is not a null pointer, the function calls rdbuf()->pubsync(). If that returns -1, the function calls setstate(badbit). It returns *this.

basic_ostream::operator<<

   basic_ostream& operator<<(
       basic_ostream& (*pf)(basic_ostream&));
   basic_ostream& operator<<(
       ios_base& (*pf)(ios_base&));
   basic_ostream& operator<<(
       basic_ios<E, T>& (*pf)(basic_ios<E, T>&));
   basic_ostream& operator<<(
       basic_streambuf<E, T> *sb);
   basic_ostream& operator<<(bool n);
   basic_ostream& operator<<(short n);
   basic_ostream& operator<<(unsigned short n);
   basic_ostream& operator<<(int n);
   basic_ostream& operator<<(unsigned int n);
   basic_ostream& operator<<(long n);
   basic_ostream& operator<<(unsigned long n);
   basic_ostream& operator<<(float n);
   basic_ostream& operator<<(double n);
   basic_ostream& operator<<(long double n);
   basic_ostream& operator<<(const void *n);

The first member function ensures that an expression of the form ostr << endl calls endl(ostr), then returns *this. The second and third functions ensure that other manipulators, such as hex behave similarly. The remaining functions are all formatted output functions.

The function:

   basic_ostream& operator<<(
       basic_streambuf<E, T> *sb);

extracts elements from sb, if sb is not a null pointer, and inserts them. Extraction stops on end-of-file, or if an extraction throws an exception (which is rethrown). It also stops, without extracting the element in question, if an insertion fails. If the function inserts no elements, or if an extraction throws an exception, the function calls setstate(failbit). In any case, the function returns *this.

The function:

   basic_ostream& operator<<(bool n);

converts n to a boolean field and inserts it by calling use_facet<num_put<E, OutIt>(getloc()). put(OutIt( rdbuf()), *this, getloc(), n). Here, OutIt is defined as ostreambuf_iterator<E, T>. The function returns *this.

The functions:

   basic_ostream& operator<<(short n);
   basic_ostream& operator<<(unsigned short n);
   basic_ostream& operator<<(int n);
   basic_ostream& operator<<(unsigned int n);
   basic_ostream& operator<<(long n);
   basic_ostream& operator<<(unsigned long n);
   basic_ostream& operator<<(const void *n);

each convert n to a numeric field and insert it by calling use_facet<num_put<E, OutIt>(getloc()). put(OutIt( rdbuf()), *this, getloc(), n). Here, OutIt is defined as ostreambuf_iterator<E, T>.

The function returns *this.

The functions:

   basic_ostream& operator<<(float n);
   basic_ostream& operator<<(double n);
   basic_ostream& operator<<(long double n);

basic_ostream::opfx

   bool opfx();

If good() is true, and tie() is not a null pointer, the member function calls tie->flush(). It returns good().

You should not call opfx directly. It is called as needed by an object of class sentry.

basic_ostream::osfx

   void osfx();

If flags() & unitbuf is nonzero, the member function calls flush(). You should not call osfx directly. It is called as needed by an object of class sentry.

basic_ostream::put

   basic_ostream& put(char_type c);

The unformatted output function inserts the element c. It returns *this.

basic_ostream::seekp

   basic_ostream& seekp(pos_type pos);
   basic_ostream& seekp(off_type off,
       ios_base::seek_dir way);

If fail() is false, the first member function calls rdbuf()-> pubseekpos(pos). If fail() is false, the second function calls rdbuf()-> pubseekoff(off, way). Both functions return *this.

basic_ostream::sentry

   class sentry {
   public:
       explicit sentry(basic_ostream<E, T>& os);
       operator bool() const;
   private:
       sentry(const sentry&);  // not defined
       sentry& operator=(const sentry&);  // not defined
       };

The nested class describes an object whose declaration structures the formatted output functions and the unformatted output functions. The constructor effectively calls os.opfx() and stores the return value. operator bool() delivers this return value. The destructor effectively calls os.osfx(), but only if uncaught_exception() returns false.

basic_ostream::tellp

   pos_type tellp();

If fail() is false, the member function returns rdbuf()-> pubseekoff(0, cur, in). Otherwise, it returns pos_type(-1).

basic_ostream::write

   basic_ostream& write(const char_type *s, streamsize n);

The unformatted output function inserts the sequence of n elements beginning at s.

endl

   template class<E, T>
       basic_ostream<E, T>& endl(basic_ostream<E, T>& os);

The manipulator calls os.put(os. widen('\n')), then calls os.flush(). It returns os.

ends

   template class<E, T>
       basic_ostream<E, T>& ends(basic_ostream<E, T>& os);

The manipulator calls os.put(E('\0')). It returns os.

flush

   template class<E, T>
       basic_ostream<E, T>& flush(basic_ostream<E, T>& os);

The manipulator calls os.flush(). It returns os.

operator<<

   template<class E, class T>
       basic_ostream<E, T>&
           operator<<(basic_ostream<E, T>& os,
               const E *s);
   template<class E, class T>
       basic_ostream<E, T>&
           operator<<(basic_ostream<E, T>& os,
               E c);
       template<class E, class T>
           basic_ostream<E, T>&
               operator<<(basic_ostream<E, T>& os,
                   const char *s);
       template<class E, class T>
           basic_ostream<E, T>&
               operator<<(basic_ostream<E, T>& os,
                   char c);
       template<class T>
           basic_ostream<char, T>&
               operator<<(basic_ostream<char, T>& os,
                   const char *s);
       template<class T>
           basic_ostream<char, T>&
               operator<<(basic_ostream<char, T>& os,
                   char c);
   template<class T>
       basic_ostream<char, T>&
           operator<<(basic_ostream<char, T>& os,
               const signed char *s);
   template<class T>
       basic_ostream<char, T>&
           operator<<(basic_ostream<char, T>& os,
               signed char c);
   template<class T>
       basic_ostream<char, T>&
           operator<<(basic_ostream<char, T>& os,
               const unsigned char *s);
   template<class T>
      basic_ostream<char, T>&
          operator<<(basic_ostream<char, T>& os,
              unsigned char c);

The template function:

   template<class E, class T>
       basic_ostream<E, T>&
           operator<<(basic_ostream<E, T>& os,
               const E *s);

is a formatted output functions that determines the length n = traits_type::length(s) of the sequence beginning at s, and inserts the sequence. If n < os.width(), then the function also inserts a repetition of os.width() - n fill characters. The repetition precedes the sequence if (os.flags() & adjustfield != left. Otherwise, the repetition follows the sequence. The function returns os.

The template function:

   template<class E, class T>
       basic_ostream<E, T>&
           operator<<(basic_ostream<E, T>& os,
               E c);

inserts the element c. If 1 < os.width(), then the function also inserts a repetition of os.width() - 1 fill characters. The repetition precedes the sequence if (os.flags() & adjustfield != left. Otherwise, the repetition follows the sequence. It returns os.

The template function:

   template<class E, class T>
       basic_ostream<E, T>&
           operator<<(basic_ostream<E, T>& os,
               const char *s);

behaves the same as:

   template<class E, class T>
       basic_ostream<E, T>&
           operator<<(basic_ostream<E, T>& os,
               const E *s);

except that each element c of the sequence beginning at s is converted to an object of type E by calling os.put(os. widen(c)).

The template function:

   template<class E, class T>
       basic_ostream<E, T>&
           operator<<(basic_ostream<E, T>& os,
               char c);

behaves the same as:

   template<class E, class T>
       basic_ostream<E, T>&
           operator<<(basic_ostream<E, T>& os,
               E c);

except that c is converted to an object of type E by calling os.put(os. widen(c)).

The template function:

   template<class T>
       basic_ostream<char, T>&
           operator<<(basic_ostream<char, T>& os,
               const char *s);

behaves the same as:

   template<class E, class T>
       basic_ostream<E, T>&
           operator<<(basic_ostream<E, T>& os,
               const E *s);

(It does not have to widen the elements before inserting them.)

The template function:

   template<class T>
       basic_ostream<char, T>&
           operator<<(basic_ostream<char, T>& os,
               char c);

behaves the same as:

   template<class E, class T>
       basic_ostream<E, T>&
           operator<<(basic_ostream<E, T>& os,
               E c);

(It does not have to widen c before inserting it.)

The template function:

   template<class T>
       basic_ostream<char, T>&
           operator<<(basic_ostream<char, T>& os,
               const signed char *s);

returns os << (const char *)s.

The template function:

   template<class T>
       basic_ostream<char, T>&
           operator<<(basic_ostream<char, T>& os,
               signed char c);

returns os << (char)c.

The template function:

   template<class T>
       basic_ostream<char, T>&
           operator<<(basic_ostream<char, T>& os,
               const unsigned char *s);

returns os << (const char *)s.

The template function:

   template<class T>
       basic_ostream<char, T>&
           operator<<(basic_ostream<char, T>& os,
               unsigned char c);

returns os << (char)c.

ostream

   typedef basic_ostream<char, char_traits<char> > ostream;

The type is a synonym for template class basic_ostream, specialized for elements of type char with default character traits.

wostream

   typedef basic_ostream<wchar_t, char_traits<wchar_t> >
       wostream;

The type is a synonym for template class basic_ostream, specialized for elements of type wchar_t with default character traits.

References

exception(C++std) , ios(C++std) , iterator(C++std) , locale(C++std) , streambuf(C++std) , string(C++std)