OSTREAM(3C++)

NAME
ostream - formatted and unformatted output

SYNOPSIS

#include <iostream.h>

typedef long streampos;
typedef long streamoff;

class unsafe_ios {
public:
	// exported types
	// stream operation mode
        enum open_mode  {
            in       = 0x01,        // open for reading
            out      = 0x02,        // open for writing
            ate      = 0x04,        // seek to eof upon original open
            app      = 0x08,        // append mode: all additions at eof
            trunc    = 0x10,        // truncate file if already exists
            nocreate = 0x20,        // open fails if file doesn't exist
            noreplace= 0x40         // open fails if file already exists
        };
	// stream seek direction
        enum seek_dir { beg=0, cur=1, end=2 };
	// formatting flags
        enum    {
            skipws    = 0x0001,     // skip whitespace on input
            left      = 0x0002,     // left-adjust output
            right     = 0x0004,     // right-adjust output
            internal  = 0x0008,     // padding after sign or base indicator
            dec       = 0x0010,     // decimal conversion
            oct       = 0x0020,     // octal conversion
            hex       = 0x0040,     // hexidecimal conversion
            showbase  = 0x0080,     // use base indicator on output
            showpoint = 0x0100,     // force decimal point (floating output)
            uppercase = 0x0200,     // upper-case hex output
            showpos   = 0x0400,     // add '+' to positive integers
            scientific= 0x0800,     // use 1.2345E2 floating notation
            fixed     = 0x1000,     // use 123.45 floating notation
            unitbuf   = 0x2000,     // flush all streams after insertion
            stdio     = 0x4000      // flush stdout, stderr after insertion
            };

	// see ios(3C++) for remainder ...
};

class unsafe_ostream : virtual public unsafe_ios {
public:
	// exported functions

	// unformatted output functions
	unsafe_ostream& put(char c);
	unsafe_ostream& write(const char* ptr, int len);

	// wide character
	unsafe_ostream& put(wchar_t wc);
	unsafe_ostream& write(const wchar_t * wptr, int len);

	// other functions
	int	opfx();
	void	osfx();
	unsafe_ostream& flush();
	unsafe_ostream& seekp(streampos pos);
	unsafe_ostream& seekp(streamoff offset, unsafe_ios::seek_dir from);
	streampos tellp();
public:
	// exported operator functions
	unsafe_ostream& operator<< (char);
	unsafe_ostream& operator<< (unsigned char);
	unsafe_ostream& operator<< (short);
	unsafe_ostream& operator<< (unsigned short);
	unsafe_ostream& operator<< (int);
	unsafe_ostream& operator<< (unsigned int);
	unsafe_ostream& operator<< (long);
	unsafe_ostream& operator<< (unsigned long);
	unsafe_ostream& operator<< (float);
	unsafe_ostream& operator<< (double);
	unsafe_ostream& operator<< (const char* buf);
	unsafe_ostream& operator<< (void* ptr);
	unsafe_ostream& operator<< (streambuf* sbufp);
	unsafe_ostream& operator<< (unsafe_ostream& (*manip)(unsafe_ostream&));
	unsafe_ostream& operator<< (unsafe_ios& (*manip)(unsafe_ios&));
public:
	// wide character
	unsafe_ostream& operator<< (wchar_t);
	unsafe_ostream& operator<< (const wchar_t*);
public:
	// exported constructors
	unsafe_ostream(streambuf* sbufp);
};

class ostream : virtual public ios, public unsafe_ostream {
public:
	// unformatted output functions
	ostream&        put(char);
	ostream&        write(const char* ptr, int n);
	ostream&        write(const unsigned char* ptr, int n);

	// wide character
	ostream&        put(wchar_t);
	ostream&        write(const wchar_t *, int);
	// other functions
	int		opfx();
	int		osfx();
	ostream&	flush();
	ostream&	seekp(streampos);
	ostream&	seekp(streamoff, seek_dir);
	streampos	tellp();
public:
	// exported operator functions
	ostream&        operator<<(char);
	ostream&        operator<<(unsigned char);
	ostream&        operator<<(short);
	ostream&        operator<<(unsigned short);
	ostream&        operator<<(int);
	ostream&        operator<<(unsigned int);
	ostream&        operator<<(long);
	ostream&        operator<<(unsigned long);
	ostream&        operator<<(float);
	ostream&        operator<<(double);
	ostream&        operator<<(const char*);
	ostream&        operator<<(void*);
	ostream&        operator<<(streambuf*);
	ostream&        operator<<(ostream& (*)(ostream&));
	ostream&        operator<<(ios& (*)(ios&));
public:
	// wide character
	ostream&        operator<< (wchar_t);
	ostream&        operator<< (const wchar_t*);
public:
		// exported constructor
                ostream(streambuf* sbufp);
};

class ostream_withassign : public ostream {
public:
	ostream_withassign();
	ostream_withassign& operator= (ostream& ostr);
	ostream_withassign& operator= (streambuf* sbufp);
};
extern ostream_withassign cout;
extern ostream_withassign cerr;
extern ostream_withassign clog;

ios&	 dec(ios&);
ios&	 hex(ios&);
ios&	 oct(ios&);
ostream& endl(ostream&);
ostream& ends(ostream&);
ostream& flush(ostream&);

unsafe_ios&     dec(unsafe_ios&) ;
unsafe_ios&     hex(unsafe_ios&) ;
unsafe_ios&     oct(unsafe_ios&) ;
unsafe_ostream& endl(unsafe_ostream& i) ;
unsafe_ostream& ends(unsafe_ostream& i) ;
unsafe_ostream& flush(unsafe_ostream&) ;

DESCRIPTION
Class ostream supports formatted and unformatted insertion (output) of data to an associated streambuf.

Class unsafe_ostream implements all of the functionality described below, but does not prevent simultaneous access by multiple threads; class ostream is a "wrapper" class that implements mutex locks around each of the respective member functions of unsafe_ostream to ensure mt-safety. Simply using the mt-safe class does not guarantee mt-safe behaviour by your application. For complete information on sharing of iostream objects between cooperating threads, see the C++ 4.1 Library Reference Manual, Chapter 5, "Using libC in a Multithreaded Environment."

  ENVIRONMENT
The discussion about thread safety applies only to Solaris 2.x. On Solaris 1.x the ``safe'' and ``unsafe'' functions behave identically.

  Constructors and Assignment

ostream(sbufp)
    Associates the streambuf pointed to by sbufp with the stream and initializes the ios state.

ostream_withassign()
    Performs no initialization.

ostream_withassign osw = sbufp
    Associates the streambuf pointed to by sbufp with osw and completely initializes osw.

ostream_withassign osw = ostr
    The streambuf associated with ostr becomes associated with osw and the constructor completely initializes osw.

Note:
    local objects of class ostream_withassign must be initialized.

  Wide character support

All operations that output wide characters to a stream set ios::failbit and stop output if they encounter a wide character with no multibyte representation in the current locale. They all call opfx().

  Output prefix and suffix functions

int i = ostr.opfx()
    Performs setup common to all insertion operations. If the error state of ostr is non-zero, opfx returns zero immediately. If a stream is tied to ostr (see tie in ios(3C++)), the tied stream is flushed. Function opfx returns zero if any error condition is encountered, non-zero otherwise. User-defined inserters should start by calling opfx.

ostr.osfx()
    Performs followup actions at the conclusion of an insertion operation. If ios::unitbuf is set, flushes the stream. If ios::stdio is set, flushes stdout and stderr. (See ios(3C++).) It has no return value. All predefined inserters call osfx, but the unformatted output functions do not. User-defined inserters should call osfx before returning.

  Formatted output (insertion) functions

The formatted output functions call opfx(). If it returns zero, no further action takes place. The functions also call osfx() before returning (if opfx() succeeded).

ostr << sbufp
    If ostr.opfx() returns non-zero, inserts all the characters into ostr that that can be extracted from the streambuf pointed to by sbufp. No padding is performed. Returns a reference to ostr. You can use this function to copy a stream efficiently, but you should be sure that neither stream is tied. For example:

    #include <iostream.h>
    main()
    {   // copy cin to cout
        cin.tie(0);
        cout.tie(0);
        cout << cin.rdbuf(); // see ios(3C++) for rdbuf
        return 0;
    }

ostr << x
    If ostr.opfx(0) returns non-zero, inserts characters representing x into ostr. If opfx returns zero, no action is taken. Any errors encountered are recorded in the error state of ostr. These functions always return a reference to ostr. User-written functions should be of the form
    ostream& operator<< (ostream&, SomeType)
    and should conform to these principles. The type of x and the format state of the ostream (see ios(3C++) determine the details of the conversion and insertion. These functions do not change the state of the ostream, except that the width variable is reset to zero after each formatted insertion. The predefined formatted inserters and their conversion rules are as follows:

char, unsigned char, signed char
    Inserts the character x into ostr without conversion.

wchar_t
    Converts the wide character to multibyte representation and inserts onto the stream. Sets ios::failbit and stops if the wide character has no multibyte representation in the current locale.

short, unsigned short
    int, unsigned int
    long, unsigned long
    The representation consists of a sequence of ``digits'' with no leading zeros. The digits and coversion are octal if ios::oct is set, hexadecimal if ios::hex is set, decimal if ios::dec or none of these is set. For decimal conversion, if x is positive and ios::showpos is set, there is a leading plus sign (`+'); if x is negative there is a leading minus sign (`-'). The octal and hexadecimal conversions are treated as unsigned; no sign is included. If ios::showbase is set, there is a leading `0' for octal conversion and a leading ``0x'' or ``0X'' for hexadecimal conversion, depending on whether ios::uppercase is set.

float, double
    The value of x is converted according to the current values in ostr of precision, width, ios::scientific, ios::fixed, and ios::uppercase. See ios(3C++).

char*
    The representation is the sequence of characters pointed to by x up to but not including the first null (0) character.

wchar_t*
    Inserts the multibyte representation of the wide characters in the array up to the first 0 wide character. Sets ios::failbit and stops if it encounters a wide character with no multibyte representation in the current locale. Note that padding is based on a field width measured in characters rather than bytes. In the current implementation, the fill character is always a single byte.

void*
    The pointer is converted as if it were an int and ios::showbase and ios::hex" were set.

  Unformatted output (insertion) functions

These operations do not call opfx() or osfx().

ostr.put(c)
    Inserts the character c into ostr. Sets the error state if the operation fails. Always returns a reference to ostr.

ostr.put(wc)
    Puts the multibyte representation of the wide character into ostr. Sets the error state if the operation fails. Always returns a reference to ostr.

ostr.write(ptr, len)
    Inserts exactly len characters starting the beginning of the char array pointed to by ptr into ostr. Sets the error state if the operation fails. Always returns a reference to ostr.

ostr.write(wptr, len)
    Puts out the multibyte representations of exactly count wide characters pointed to by wptr into ostr.

  Positioning functions

These deal with the put pointer of the streambuf associated with an ostream. See sbufpub(3C++) for a complete discussion. Multibyte input operations may cause the get pointer of the streambuf to differ from the value reported by tellg(), but seeks done on the istream rather than the streambuf will still coordinate correctly with all operations on the istream.

ostr.seekp(pos)
    ostr.seekp(off, dir)
    These set the position of the put pointer; they return a reference to ostr.

streampos pos = ostr.tellp()
    This returns the current position of the put pointer.

  Miscellaneous functions

ostr.flush()
    This causes any characters stored into the associated streambuf to be flushed; for example, written to the output file. It returns a reference to ostr.

  Predefined Manipulators

A manipulator may be used apparently as an inserted or extracted object, but many only change the state of the stream. See manip(3C++) and ios(3C++) for more information. Several manipulators are predefined for use with ostreams.

ostr << manip
    This is equivalent to the call manip(ostr).

ostr << dec
    This sets the conversion base of ostr to 10.

ostr << oct
    This sets the conversion base of ostr to 8.

ostr << hex
    This sets the conversion base of ostr to 16.

ostr << endl
    This ends a line by inserting a newline and flushing ostr.

ostr << ends
    This ends a string by inserting null (0) character into ostr.

ostr << flush
    This is equivalent to calling ostr.flush().

SEE ALSO

ios.intro(3C++), ios(3C++), manip(3C++), sbufpub(3C++),

C++ 4.1 Library Reference Manual:

Chapter 4, "The Iostream Library",

Chapter 5, "Using libC in a Multithreaded Environment."