<ostream>

        // DECLARATIONS
class ostream;

        // INSERTERS
ostream&
    operator<<(ostream& ostr, const char *str);
ostream&
    operator<<(ostream& ostr, char ch);
ostream&
    operator<<(ostream& ostr, const signed char *str);
ostream&
    operator<<(ostream& ostr, signed char ch);
ostream&
    operator<<(ostream& ostr, const unsigned char *str);
ostream&
    operator<<(ostream& ostr, unsigned char ch);

        // MANIPULATORS
ostream& endl(ostream& ostr);
ostream& ends(ostream& ostr);
ostream& flush(ostream& ostr);
        // END OF DECLARATIONS

Include the iostreams standard header <ostream> to define class 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.)

ostream

ostream · flush · operator<< · put · seekp · sentry · tellp · write

class ostream : public ios {
public:
    explicit ostream(streambuf *strbuf);
    class sentry;
    virtual ~ostream();
    ostream& operator<<(
        ostream& (*pfn)(ostream&));
    ostream& operator<<(
        ios_base;& (*pfn)(ios_base&));
    ostream& operator<<(
        ios& (*pfn)(ios&));
    ostream& operator<<(
        streambuf *strbuf);
    ostream& operator<<(bool val);
    ostream& operator<<(short val);
    ostream& operator<<(unsigned short val);
    ostream& operator<<(int val);
    ostream& operator<<(unsigned int val);
    ostream& operator<<(long val);
    ostream& operator<<(unsigned long val);
    ostream& operator<<(float val);
    ostream& operator<<(double val);
    ostream& operator<<(long double val);
    ostream& operator<<(const void *val);
    ostream& put(char_type ch);
    ostream& write(char_type *str, streamsize count);
    ostream& flush();
    pos_type tellp();
    ostream& seekp(pos_type pos);
    ostream& seekp(off_type off,
        ios_base::seek_dir way);
    };

The class describes an object that controls insertion of elements and encoded objects into a stream buffer with elements of type char, also known as char_type, whose character traits are determined by the class char_traits, 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 ostream stores only a public base object of class ios

ostream::ostream

explicit ostream(streambuf *strbuf);

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

ostream::flush

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.

ostream::operator<<

ostream& operator<<(
    ostream& (*pfn)(ostream&));
ostream& operator<<(
    ios_base& (*pfn)(ios_base&));
ostream& operator<<(
    ios& (*pfn)(ios&));
ostream& operator<<(
    streambuf *strbuf);
ostream& operator<<(bool val);
ostream& operator<<(short val);
ostream& operator<<(unsigned short val);
ostream& operator<<(int val);
ostream& operator<<(unsigned int val);
ostream& operator<<(long val);
ostream& operator<<(unsigned long val);
ostream& operator<<(float val);
ostream& operator<<(double val);
ostream& operator<<(long double val);
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:

ostream& operator<<(
    streambuf *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.

All the remaining functions generate an output field and insert it. The output output field is generated by the same rules used by the print functions for generating a series of char elements to a file. Where a print function pads a field with either spaces or the digit 0, however, the function instead uses fill. The equivalent print conversion specification is determined as described for each function below.

Padding occurs only if the minimum number of elements N required to specify the output field is less than width(). Such padding consists of a sequence of N - width() copies of fill(). Padding then occurs as follows:

• If flags() & ios_base::adjustfield == ios_base::left, the flag - is prepended to the conversion specification. (Padding occurs after the generated text.)
• If flags() & ios_base::adjustfield == ios_base::internal, the flag 0 is prepended. (For a numeric output field, padding occurs where the print functions pad with 0.)
• Otherwise, no additional flag is prepended. (Padding occurs before the generated sequence.)

The function:

ostream& operator<<(bool val);

converts val to a boolean output field and inserts it as an array of char, with a conversion specifier of s.

A boolean output field takes one of two forms. If flags() & ios_base::boolalpha is false, the generated sequence is either 0 (for false) or 1 (for true). Otherwise, the generated sequence is either false (for false), or true (for true). The function then calls width(0) to reset the field width to zero. The function returns *this.

The functions:

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

each convert val to an integer output field and inserts it. The equivalent print conversion specification is determined as follows:

• If flags() & ios_base::basefield == ios_base::oct, the conversion specification is lo and the converted value is (long)val.
• If flags() & ios_base::basefield == ios_base::hex, the conversion specification is lx and the converted value is (unsigned long)val.
• Otherwise, the conversion specification is ld and the converted value is (long)val.

If width() is nonzero, a field width of this value is prepended. The function then calls width(0) to reset the field width to zero.

Finally:

• If flags() & ios_base::showpos is nonzero, the flag + is prepended to the conversion specification.
• If flags() & ios_base::showbase is nonzero, the flag # is prepended to the conversion specification.

The function returns *this.

The functions:

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

each convert val to a floating-point output field and insert it. A period (.) separates the integer digits from the fraction digits. The equivalent print conversion specification is determined as follows:

• If flags() & ios_base::floatfield == ios_base::fixed, the conversion specification is f.
• If flags() & ios_base::floatfield == ios_base::scientific, the conversion specification is e. If flags() & ios_base::uppercase is nonzero, e is replaced with E.
• Otherwise, the conversion specification is g. If flags() & ios_base::uppercase is nonzero, g is replaced with G.

If val has type double, the function prepends l to the conversion specification. If val has type long double, it prepends L to the conversion specification.

If flags() & ios_base::fixed is nonzero, or if precision() is greater than zero, a precision with the value precision() is prepended to the conversion specification. Any padding behaves the same as for an integer output field.

If width() is nonzero, a field width of this value is prepended. The function then calls width(0) to reset the field width to zero. Finally:

• If flags() & ios_base::showpos is nonzero, the flag + is prepended to the conversion specification.
• If flags() & ios_base::showpoint is nonzero, the flag # is prepended to the conversion specification.

ostream::put

ostream& put(char_type ch);

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

ostream::seekp

ostream& seekp(pos_type pos);
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.

ostream::sentry

class sentry {
public:
    explicit sentry(ostream& 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 flags() & unitbuf is nonzero, the destructor calls flush().

ostream::tellp

pos_type tellp();

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

ostream::write

ostream& write(const char_type *str, streamsize count);

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

endl

ostream endl(ostream& ostr);

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

ends

ostream& ends(ostream& ostr);

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

flush

ostream& flush(ostream& ostr);

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

operator<<

ostream&
    operator<<(ostream& ostr, const char *str);
ostream&
    operator<<(ostream& ostr, char ch);
ostream&
    operator<<(ostream& ostr, const signed char *str);
ostream&
    operator<<(ostream& ostr, signed char ch);
ostream&
    operator<<(ostream& ostr, const unsigned char *str);
ostream&
    operator<<(ostream& ostr, unsigned char ch);

All of these functions are formatted output functions. The function:

ostream&
    operator<<(ostream& ostr, const char *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 function:

ostream&
    operator<<(ostream& ostr, char 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 function:

ostream&
    operator<<(ostream& ostr, const signed char *str);

returns ostr << (const char *)str.

The function:

ostream&
    operator<<(ostream& ostr, signed char ch);

returns ostr << (char)ch.

The function:

ostream&
    operator<<(ostream& ostr, const unsigned char *str);

returns ostr << (const char *)str.

The function:

ostream&
    operator<<(ostream& ostr, unsigned char ch);

returns ostr << (char)ch.

See also the Table of Contents and the Index.

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