<ostream>

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

        // INSERTERS
template<class Elem, class Tr>
    basic_ostream<Elem, Tr>&
        operator<<(basic_ostream<Elem, Tr>& ostr,
            const Elem *str);
template<class Elem, class Tr>
    basic_ostream<Elem, Tr>&
        operator<<(basic_ostream<Elem, Tr>& ostr,
            Elem ch);
template<class Elem, class Tr>
    basic_ostream<Elem, Tr>&
        operator<<(basic_ostream<Elem, Tr>& ostr,
            const char *str);
template<class Elem, class Tr>
    basic_ostream<Elem, Tr>&
        operator<<(basic_ostream<Elem, Tr>& ostr,
            char ch);
template<class Tr>
    basic_ostream<char, Tr>&
        operator<<(basic_ostream<char, Tr>& ostr,
            const char *str);
template<class Tr>
    basic_ostream<char, Tr>&
        operator<<(basic_ostream<char, Tr>& ostr,
            char ch);
template<class Tr>
    basic_ostream<char, Tr>&
        operator<<(basic_ostream<char, Tr>& ostr,
            const signed char *str);
template<class Tr>
    basic_ostream<char, Tr>&
        operator<<(basic_ostream<char, Tr>& ostr,
            signed char ch);
template<class Tr>
    basic_ostream<char, Tr>&
        operator<<(basic_ostream<char, Tr>& ostr,
            const unsigned char *str);
template<class Tr>
    basic_ostream<char, Tr>&
        operator<<(basic_ostream<char, Tr>& ostr,
            unsigned char ch);

        // MANIPULATORS
template class<Elem, Tr>
    basic_ostream<Elem, Tr>&
        endl(basic_ostream<Elem, Tr>& ostr);
template class<Elem, Tr>
    basic_ostream<Elem, Tr>&
        ends(basic_ostream<Elem, Tr>& ostr);
template class<Elem, Tr>
    basic_ostream<Elem, Tr>&
        flush(basic_ostream<Elem, Tr>& ostr);
    };

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<< · put · seekp · sentry · tellp · write

template <class Elem, class Tr = char_traits<Elem> >
    class basic_ostream
        : virtual public basic_ios<Elem, Tr> {
public:
    typedef typename basic_ios<Elem, Tr>::char_type char_type;
    typedef typename basic_ios<Elem, Tr>::traits_type traits_type;
    typedef typename basic_ios<Elem, Tr>::int_type int_type;
    typedef typename basic_ios<Elem, Tr>::pos_type pos_type;
    typedef typename basic_ios<Elem, Tr>::off_type off_type;
    explicit basic_ostream(basic_streambuf<Elem, Tr> *strbuf);
    class sentry;
    virtual ~basic_ostream();
    basic_ostream& operator<<(
        basic_ostream& (*pfn)(basic_ostream&));
    basic_ostream& operator<<(
        ios_base;& (*pfn)(ios_base&));
    basic_ostream& operator<<(
        basic_ios<Elem, Tr>& (*pfn)(basic_ios<Elem, Tr>&));
    basic_ostream& operator<<(
        basic_streambuf<Elem, Tr> *strbuf);
    basic_ostream& operator<<(bool val);
    basic_ostream& operator<<(short val);
    basic_ostream& operator<<(unsigned short val);
    basic_ostream& operator<<(int val);
    basic_ostream& operator<<(unsigned int val);
    basic_ostream& operator<<(long val);
    basic_ostream& operator<<(unsigned long val);
    basic_ostream& operator<<(float val);
    basic_ostream& operator<<(double val);
    basic_ostream& operator<<(long double val);
    basic_ostream& operator<<(const void *val);
    basic_ostream& put(char_type ch);
    basic_ostream& write(char_type *str, streamsize count);
    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 encoded objects into a stream buffer with elements of type Elem, also known as char_type, whose character traits are determined by the class Tr, 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<<(Elem)
    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_ostream<Elem, Tr> stores only a virtual public base object of class basic_ios<Elem, Tr>

basic_ostream::basic_ostream

explicit basic_ostream(basic_streambuf<Elem, Tr> *strbuf);

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

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& (*pfn)(basic_ostream&));
basic_ostream& operator<<(
    ios_base& (*pfn)(ios_base&));
basic_ostream& operator<<(
    basic_ios<Elem, Tr>& (*pfn)(basic_ios<Elem, Tr>&));
basic_ostream& operator<<(
    basic_streambuf<Elem, Tr> *strbuf);
basic_ostream& operator<<(bool val);
basic_ostream& operator<<(short val);
basic_ostream& operator<<(unsigned short val);
basic_ostream& operator<<(int val);
basic_ostream& operator<<(unsigned int val);
basic_ostream& operator<<(long val);
basic_ostream& operator<<(unsigned long val);
basic_ostream& operator<<(float val);
basic_ostream& operator<<(double val);
basic_ostream& operator<<(long double val);
basic_ostream& operator<<(const void *val);

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<Elem, Tr> *strbuf);

extracts elements from strbuf, if strbuf is not a null pointer, and inserts them. If strbuf is a null pointer, the function calls setstate(badbit). Otherwise, 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 val);

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

The functions:

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

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

The function returns *this.

The functions:

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

each convert val to a numeric field and insert it by calling use_facet<num_put<Elem, OutIt>(getloc()). put(OutIt( rdbuf()), *this, getloc(), val). Here, OutIt is defined as ostreambuf_iterator<Elem, Tr>. The function returns *this.

basic_ostream::put

basic_ostream& put(char_type ch);

The unformatted output function inserts the element ch. 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 newpos = rdbuf()-> pubseekpos(pos, out), for some pos_type temporary object newpos. If fail() is false, the second function calls newpos = rdbuf()-> pubseekoff(off, way, out). In either case, if (off_type)newpos == (off_type)(-1) (the positioning operation fails) the function calls istr.setstate(failbit). Both functions return *this.

basic_ostream::sentry

class sentry {
public:
    explicit sentry(basic_ostream<Elem, Tr>& ostr);
    operator bool() const;
    ~sentry();
private:
    sentry(const sentry&);  // not defined
    sentry& operator=(const sentry&);  // not defined
    bool status;
    };

The nested class describes an object whose declaration structures the formatted output functions and the unformatted output functions. If ostr.good() is true, and ostr.tie() is not a null pointer, the constructor calls ostr.tie->flush(). The constructor then stores the value returned by ostr.good() in status. A later call to operator bool() delivers this stored value.

If

uncaught_exception() returns false and flags() & unitbuf is nonzero, the destructor calls flush().

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 *str, streamsize count);

The unformatted output function inserts the sequence of count elements beginning at str.

endl

template class<Elem, Tr>
    basic_ostream<Elem, Tr>& endl(basic_ostream<Elem, Tr>& ostr);

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

ends

template class<Elem, Tr>
    basic_ostream<Elem, Tr>& ends(basic_ostream<Elem, Tr>& ostr);

The manipulator calls ostr.put(Elem('\0')). It returns ostr.

flush

template class<Elem, Tr>
    basic_ostream<Elem, Tr>& flush(basic_ostream<Elem, Tr>& ostr);

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

operator<<

template<class Elem, class Tr>
    basic_ostream<Elem, Tr>&
        operator<<(basic_ostream<Elem, Tr>& ostr,
            const Elem *str);
template<class Elem, class Tr>
    basic_ostream<Elem, Tr>&
        operator<<(basic_ostream<Elem, Tr>& ostr,
            Elem ch);
    template<class Elem, class Tr>
        basic_ostream<Elem, Tr>&
            operator<<(basic_ostream<Elem, Tr>& ostr,
                const char *str);
    template<class Elem, class Tr>
        basic_ostream<Elem, Tr>&
            operator<<(basic_ostream<Elem, Tr>& ostr,
                char ch);
    template<class Tr>
        basic_ostream<char, Tr>&
            operator<<(basic_ostream<char, Tr>& ostr,
                const char *str);
    template<class Tr>
        basic_ostream<char, Tr>&
            operator<<(basic_ostream<char, Tr>& ostr,
                char ch);
template<class Tr>
    basic_ostream<char, Tr>&
        operator<<(basic_ostream<char, Tr>& ostr,
            const signed char *str);
template<class Tr>
    basic_ostream<char, Tr>&
        operator<<(basic_ostream<char, Tr>& ostr,
            signed char ch);
template<class Tr>
    basic_ostream<char, Tr>&
        operator<<(basic_ostream<char, Tr>& ostr,
            const unsigned char *str);
template<class Tr>
   basic_ostream<char, Tr>&
       operator<<(basic_ostream<char, Tr>& ostr,
           unsigned char ch);

The template function:

template<class Elem, class Tr>
    basic_ostream<Elem, Tr>&
        operator<<(basic_ostream<Elem, Tr>& ostr,
            const Elem *str);

determines the length N = traits_type::length(str) of the sequence beginning at str, and inserts the sequence. If N < ostr.width(), then the function also inserts a repetition of ostr.width() - N fill characters. The repetition precedes the sequence if (ostr.flags() & adjustfield != left. Otherwise, the repetition follows the sequence. The function returns ostr.

The template function:

template<class Elem, class Tr>
    basic_ostream<Elem, Tr>&
        operator<<(basic_ostream<Elem, Tr>& ostr,
            Elem ch);

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

The template function:

template<class Elem, class Tr>
    basic_ostream<Elem, Tr>&
        operator<<(basic_ostream<Elem, Tr>& ostr,
            const char *str);

behaves the same as:

template<class Elem, class Tr>
    basic_ostream<Elem, Tr>&
        operator<<(basic_ostream<Elem, Tr>& ostr,
            const Elem *str);

except that each element ch of the sequence beginning at str is converted to an object of type Elem by calling ostr.put(ostr. widen(ch)).

The template function:

template<class Elem, class Tr>
    basic_ostream<Elem, Tr>&
        operator<<(basic_ostream<Elem, Tr>& ostr,
            char ch);

behaves the same as:

template<class Elem, class Tr>
    basic_ostream<Elem, Tr>&
        operator<<(basic_ostream<Elem, Tr>& ostr,
            Elem ch);

except that ch is converted to an object of type Elem by calling ostr.put(ostr. widen(ch)).

The template function:

template<class Tr>
    basic_ostream<char, Tr>&
        operator<<(basic_ostream<char, Tr>& ostr,
            const char *str);

behaves the same as:

template<class Elem, class Tr>
    basic_ostream<Elem, Tr>&
        operator<<(basic_ostream<Elem, Tr>& ostr,
            const Elem *str);

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

The template function:

template<class Tr>
    basic_ostream<char, Tr>&
        operator<<(basic_ostream<char, Tr>& ostr,
            char ch);

behaves the same as:

template<class Elem, class Tr>
    basic_ostream<Elem, Tr>&
        operator<<(basic_ostream<Elem, Tr>& ostr,
            Elem ch);

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

The template function:

template<class Tr>
    basic_ostream<char, Tr>&
        operator<<(basic_ostream<char, Tr>& ostr,
            const signed char *str);

returns ostr << (const char *)str.

The template function:

template<class Tr>
    basic_ostream<char, Tr>&
        operator<<(basic_ostream<char, Tr>& ostr,
            signed char ch);

returns ostr << (char)ch.

The template function:

template<class Tr>
    basic_ostream<char, Tr>&
        operator<<(basic_ostream<char, Tr>& ostr,
            const unsigned char *str);

returns ostr << (const char *)str.

The template function:

template<class Tr>
    basic_ostream<char, Tr>&
        operator<<(basic_ostream<char, Tr>& ostr,
            unsigned char ch);

returns ostr << (char)ch.

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.

See also the Table of Contents and the Index.

Copyright © 1992-2002 by P.J. Plauger. All rights reserved.