<ostream>


// DECLARATIONS
    class ostream;
//      INSERTERS
     ostream&
        operator<<(ostream& os, const char *s);
    ostream&
        operator<<(ostream& os, char c);
    ostream&
        operator<<(ostream& os, const signed char *s);
    ostream&
        operator<<(ostream& os, signed char c);
    ostream&
        operator<<(ostream& os, const unsigned char *s);
    ostream&
        operator<<(ostream& os, unsigned char c);
//      MANIPULATORS
    ostream& endl(ostream& os);
    ostream& ends(ostream& os);
    ostream& flush(ostream& os);
// 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<< · opfx · osfx · put · seekp · sentry · tellp · write


class ostream : public ios {
public:
    explicit ostream(streambuf *sb);
    class sentry;
    virtual ~ostream();
    bool opfx();
    void osfx();
    ostream& operator<<(
        ostream& (*pf)(ostream&));
    ostream& operator<<(
        ios_base;& (*pf)(ios_base&));
    ostream& operator<<(
        ios& (*pf)(ios&));
    ostream& operator<<(
        streambuf *sb);
    ostream& operator<<(bool n);
    ostream& operator<<(short n);
    ostream& operator<<(unsigned short n);
    ostream& operator<<(int n);
    ostream& operator<<(unsigned int n);
    ostream& operator<<(long n);
    ostream& operator<<(unsigned long n);
    ostream& operator<<(float n);
    ostream& operator<<(double n);
    ostream& operator<<(long double n);
    ostream& operator<<(const void *n);
    ostream& put(char_type c);
    ostream& write(char_type *s, streamsize n);
    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 (...)
            {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 istream stores only a public base object of class ios

ostream::ostream

explicit ostream(streambuf *sb);

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

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

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

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:

The function:

ostream& operator<<(bool n);

converts n 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 n);
ostream& operator<<(unsigned short n);
ostream& operator<<(int n);
ostream& operator<<(unsigned int n);
ostream& operator<<(long n);
ostream& operator<<(unsigned long n);
ostream& operator<<(const void *n);

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

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:

The function returns *this.

The functions:

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

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

If n has type double, the function prepends l to the conversion specification. If n 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:

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.

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.

ostream::put

ostream& put(char_type c);

The unformatted output function inserts the element c. 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 rdbuf()-> pubseekpos(pos). If fail() is false, the second function calls rdbuf()-> pubseekoff(off, way). Both functions return *this.

ostream::sentry

class sentry {
public:
    explicit sentry(ostream& 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().

ostream::tellp

pos_type tellp();

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

ostream::write

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

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

endl

ostream endl(ostream& os);

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

ends

ostream& ends(ostream& os);

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

flush

ostream& flush(ostream& os);

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

operator<<

ostream&
    operator<<(ostream& os, const char *s);
ostream&
    operator<<(ostream& os, char c);
ostream&
    operator<<(ostream& os, const signed char *s);
ostream&
    operator<<(ostream& os, signed char c);
ostream&
    operator<<(ostream& os, const unsigned char *s);
ostream&
    operator<<(ostream& os, unsigned char c);

The function:

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

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

ostream&
    operator<<(ostream& os, const signed char *s);

returns os << (const char *)s.

The function:

ostream&
    operator<<(ostream& os, signed char c);

returns os << (char)c.

The function:

ostream&
    operator<<(ostream& os, const unsigned char *s);

returns os << (const char *)s.

The function:

ostream&
    operator<<(ostream& os, unsigned char c);

returns os << (char)c.


See also the Table of Contents and the Index.

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