OSTREAM(3CC4)OSTREAM(3CC4)NAMEostream - 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(3CC4) 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 be‐
haviour by your application. For complete information on sharing of
iostream objects between cooperating threads, see the C++ Library Ref‐
erence, Chapter 4, "Using Classic iostream in a Multithreaded Environ‐
ment."
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 com‐
pletely 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(3CC4)), 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(3CC4).)
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(3CC4) for rdbuf
return 0;
}
ostr << x
If ostr.opfx(0) returns non-zero, inserts characters represent‐
ing 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(3CC4)
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 inser‐
tion. 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(3CC4).
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(3CC4) 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 refer‐
ence 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(3CC4)
and ios(3CC4) for more information. Several manipulators are prede‐
fined 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 ALSOios.intro(3CC4), ios(3CC4), manip(3CC4), sbufpub(3CC4),
C++ Library Reference
Chapter 3, "The Classic iostream Library",
Chapter 4, "Using Classic iostream in a Multithreaded Environ‐
ment."
18 June 1998 OSTREAM(3CC4)
