<ostream>


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

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:
    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 encoded objects into a stream buffer with elements of type E, also known as char_type, whose 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 (...)
            {if (exceptions() & badbit)
                throw;
            setstate(badbit); }}
    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 (...)
            {if (rdstate() & badbit)
                throw;
            setstate(badbit); }}
    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);

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.

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 streampos(-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.


See also the Table of Contents and the Index.

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