`<ostream>`

basic_ostream · endl · ends · flush · operator<< · ostream · wostream · swap

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

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

template<class Elem, class Tr, class Ty>
    basic_ostream<Elem, Tr>&
        operator<<(basic_ostream<Elem, Tr>&& ostr,
            Ty val); [added with C++11]

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

        // TEMPLATE FUNCTIONS
template<class Elem, class Tr>
    void swap(basic_ostream<Elem, Tr>& left,
        basic_ostream<Elem, Tr>& right); [added with C++11]
}  // namespace std

`basic_ostream`

basic_ostream · flush · operator= · operator<< · put · seekp · sentry · swap · 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);

protected:
    basic_ostream(basic_ostream&& right); [added with C++11]
    basic_ostream(const basic_ostream& right) = delete; [added with C++11]

    basic_ostream& operator=(basic_ostream&& right); [added with C++11]
    basic_ostream& operator=(const basic_ostream& right) = delete; [added with C++11]
    void swap(basic_ostream& right); [added with C++11]

public:

    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<<(long long val); [added with C++11]
    basic_ostream& operator<<(unsigned long long val); [added with C++11]

    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> }
    width(0);    // except for operator<<(Elem)
    setstate(state);
    return (*this);

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> }
    setstate(state);
    return (*this);

Still other member functions are positioning functions. They follow the pattern:

    iostate state = goodbit;
    const sentry ok(*this, true);
    if (!fail())
        {<perform positioning operation
        accumulate flags in state> }
    setstate(state);

All 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);
basic_ostream(basic_ostream&& right); [added with C++11]

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

The second constructor initializes the base class by calling move(right).

`basic_ostream::flush`

basic_ostream& flush();

If rdbuf() is not a null pointer, the unformatted output 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<<(long long val); [added with C++11]
basic_ostream& operator<<(unsigned long long val); [added with C++11]

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 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 remaining functions are all formatted output functions.

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<<(long long val); [added with C++11]
basic_ostream& operator<<(unsigned long long val); [added with C++11]

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

`basic_ostream::operator=`

basic_ostream& operator=(basic_ostream&& right); [added with C++11]

The member operator calls swap(right).

`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 positioning function calls newpos = rdbuf()-> pubseekpos(pos, out), for some pos_type temporary object newpos. If fail() is false, the second positioning 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 setstate(failbit). Both functions return *this.

`basic_ostream::sentry`

class sentry {
public:
    explicit sentry(basic_ostream<Elem, Tr>& ostr);
    explicit operator bool() const;
    ~sentry();

    sentry(const sentry& right) = delete; [added with C++11]
    sentry& operator=(const sentry& right) = delete; [added with C++11]

private:
    bool status;
    };

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

If uncaught_exception() returns false, and good() is true, and flags() & unitbuf is nonzero, the destructor calls pubsync(). If that function returns -1, the destructor calls setstate(badbit) without propagating any exception.

`basic_ostream::swap`

void swap(basic_ostream& right); [added with C++11]

The member function calls swap(right).

`basic_ostream::tellp`

pos_type tellp();

If fail() is false, the positioning 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);

template<class Elem, class Tr, class Ty>
    basic_ostream<Elem, Tr>&
        operator<<(basic_ostream<Elem, Tr>&& ostr,
            Ty val); [added with C++11]

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.

The template function:

template<class Elem, class Tr, class Ty>
    basic_ostream<Elem, Tr>&
        operator<<(basic_ostream<char, Tr>&& ostr,
            Ty val); [added with C++11]

returns ostr << val (and converts an rvalue reference to ostr to an lvalue in the process).

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

`swap`

template<class Elem, class Tr>
    void swap(basic_ostream<Elem, Tr>& left,
        basic_ostream<Elem, Tr>& right); [added with C++11]

The template function executes left.swap(right).

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