.\" '\" tep .\" to invoke 'tbl', 'eqn', 'pic' in the proper order .\" .\" @(#)ostream.3 1.1 93/04/27 SMI; .\" .TH OSTREAM 3CC4 "18 June 1998" .\" .SH NAME ostream \- formatted and unformatted output .SH SYNOPSIS .LP .nf .ft B #include .sp .5v typedef long streampos; typedef long streamoff; .sp .5v 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 }; .sp .5v // \fIsee \fBios\fR(3CC4)\fI for remainder ...\fB }; .sp .5v class unsafe_ostream : virtual public unsafe_ios { public: // exported functions .sp .5v // unformatted output functions unsafe_ostream& put(char c); unsafe_ostream& write(const char* ptr, int len); .sp .5v // wide character unsafe_ostream& put(wchar_t wc); unsafe_ostream& write(const wchar_t * wptr, int len); .sp .5v // 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); }; .sp .5v 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); .sp .5v // 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); }; .sp .5v 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; .sp .5v ios& dec(ios&); ios& hex(ios&); ios& oct(ios&); ostream& endl(ostream&); ostream& ends(ostream&); ostream& flush(ostream&); .sp .5v 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&) ; .ft R .fi .\" .SH DESCRIPTION Class .B ostream supports formatted and unformatted insertion (output) of data to an associated \fBstreambuf\fR. .PP Class .BR unsafe_ostream implements all of the functionality described below, but does not prevent simultaneous access by multiple threads; class .BR ostream is a "wrapper" class that implements mutex locks around each of the respective member functions of .BR 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 .IR "C++ Library Reference, Chapter 4, "Using Classic \fIiostream\fR in a Multithreaded Environment." .PP .SS "Constructors and Assignment" .TP .B ostream(sbufp) Associates the \fBstreambuf\fR pointed to by \fBsbufp\fR with the stream and initializes the \fBios\fR state. .TP .B ostream_withassign() Performs no initialization. .TP .B "ostream_withassign osw = sbufp" Associates the \fBstreambuf\fR pointed to by \fBsbufp\fR with \fBosw\fR and completely initializes \fBosw\fR. .TP .B "ostream_withassign osw = ostr" The \fBstreambuf\fR associated with \fBostr\fR becomes associated with \fBosw\fR and the constructor completely initializes \fBosw\fR. .TP .B Note: local objects of class \fBostream_withassign\fR must be initialized. .\" .SS "Wide character support" .LP All operations that output wide characters to a stream set \fBios::failbit\fR and stop output if they encounter a wide character with no multibyte representation in the current locale. They all call \fBopfx()\fR. .SS "Output prefix and suffix functions" .TP .B "int i = ostr.opfx()" Performs setup common to all insertion operations. If the error state of \fBostr\fR is non-zero, \fBopfx\fR returns zero immediately. If a stream is \fItied\fR to \fBostr\fR (see \fBtie\fR in \fBios\fR(3CC4)), the tied stream is flushed. Function \fBopfx\fR returns zero if any error condition is encountered, non-zero otherwise. User-defined inserters should start by calling \fBopfx\fR. .TP .B "ostr.osfx()" Performs followup actions at the conclusion of an insertion operation. If \fBios::unitbuf\fR is set, flushes the stream. If \fBios::stdio\fR is set, flushes \fBstdout\fR and \fBstderr\fR. (See \fBios\fR(3CC4).) It has no return value. All predefined inserters call \fBosfx\fR, but the unformatted output functions do not. User-defined inserters should call \fBosfx\fR before returning. .\" .SS "Formatted output (insertion) functions" .LP The formatted output functions call \fBopfx()\fR. If it returns zero, no further action takes place. The functions also call \fBosfx()\fR before returning (if \fBopfx()\fR succeeded). .TP .B "ostr << sbufp" If \fBostr.opfx()\fR returns non-zero, inserts all the characters into \fBostr\fR that that can be extracted from the \fBstreambuf\fR pointed to by \fBsbufp\fR. No padding is performed. Returns a reference to \fBostr\fR. You can use this function to copy a stream efficiently, but you should be sure that neither stream is tied. For example: .sp .in +1i .nf .ft B #include main() { // copy cin to cout cin.tie(0); cout.tie(0); cout << cin.rdbuf(); // see \fIios(3CC4)\fB for rdbuf return 0; } .ft R .fi .in -5i .TP .B "ostr << x" If \fBostr.opfx(0)\fR returns non-zero, inserts characters representing \fBx\fR into \fBostr\fR. If \fBopfx\fR returns zero, no action is taken. Any errors encountered are recorded in the error state of \fBostr\fR. These functions always return a reference to \fBostr\fR. User-written functions should be of the form .ti +.5i .B "ostream& operator<< (ostream&, SomeType)" .br and should conform to these principles. The type of \fBx\fR and the format state of the \fBostream\fR (see \fBios\fR(3CC4) determine the details of the conversion and insertion. These functions do not change the state of the \fBostream\fR, except that the \fBwidth\fR variable is reset to zero after each formatted insertion. The predefined formatted inserters and their conversion rules are as follows: .in +.5i .TP .B "char, unsigned char, signed char" Inserts the character \fBx\fR into \fBostr\fR without conversion. .TP .B "wchar_t" Converts the wide character to multibyte representation and inserts onto the stream. Sets \fBios::failbit\fR and stops if the wide character has no multibyte representation in the current locale. .TP .B "short, unsigned short" .in -.5i .B "int, unsigned int" .br .B "long, unsigned long" .in +.5i The representation consists of a sequence of ``digits'' with no leading zeros. The digits and coversion are octal if \fBios::oct\fR is set, hexadecimal if \fBios::hex\fR is set, decimal if \fBios::dec\fR or none of these is set. For decimal conversion, if \fBx\fR is positive and \fBios::showpos\fR is set, there is a leading plus sign (`+'); if \fBx\fR is negative there is a leading minus sign (`\-'). The octal and hexadecimal conversions are treated as unsigned; no sign is included. If \fBios::showbase\fR is set, there is a leading `0' for octal conversion and a leading ``0x'' or ``0X'' for hexadecimal conversion, depending on whether \fBios::uppercase\fR is set. .TP .B "float, double" The value of \fBx\fR is converted according to the current values in \fBostr\fR of .BR precision ", " width ", " .BR ios::scientific ", " ios::fixed ", and " .BR ios::uppercase . See \fBios\fR(3CC4). .TP .B "char*" The representation is the sequence of characters pointed to by \fBx\fR up to but not including the first null (0) character. .TP .B "wchar_t*" Inserts the multibyte representation of the wide characters in the array up to the first 0 wide character. Sets \fBios::failbit\fR 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. .TP .B "void*" The pointer is converted as if it were an \fBint\fR and .BR ios::showbase " and " ios::hex" were set. .in -.5i .\" .SS "Unformatted output (insertion) functions" .LP These operations do not call \fBopfx()\fR or \fBosfx()\fR. .TP .B "ostr.put(c)" Inserts the character \fBc\fR into \fBostr\fR. Sets the error state if the operation fails. Always returns a reference to \fBostr\fR. .TP .B "ostr.put(wc)" Puts the multibyte representation of the wide character into \fBostr\fR. Sets the error state if the operation fails. Always returns a reference to \fBostr\fR. .TP .B "ostr.write(ptr, len)" Inserts exactly \fBlen\fR characters starting the beginning of the \fBchar\fR array pointed to by \fBptr\fR into \fBostr\fR. Sets the error state if the operation fails. Always returns a reference to \fBostr\fR. .TP .B "ostr.write(wptr, len)" Puts out the multibyte representations of exactly count wide characters pointed to by \fBwptr\fR into \fBostr\fR. .SS "Positioning functions" .LP These deal with the \fIput\fR pointer of the \fBstreambuf\fR associated with an \fBostream\fR. See .BR sbufpub (3CC4) for a complete discussion. Multibyte input operations may cause the get pointer of the streambuf to differ from the value reported by \fBtellg()\fR, but seeks done on the istream rather than the \fBstreambuf\fR will still coordinate correctly with all operations on the \fBistream\fR. .TP .B "ostr.seekp(pos)" .in -.5i .B "ostr.seekp(off, dir)" .in +.5i These set the position of the \fIput\fR pointer; they return a reference to \fBostr\fR. .TP .B "streampos pos = ostr.tellp()" This returns the current position of the \fBput\fR pointer. .\" .SS "Miscellaneous functions" .TP .B "ostr.flush()" This causes any characters stored into the associated \fBstreambuf\fR to be flushed; for example, written to the output file. It returns a reference to \fBostr\fR. .\" .SS "Predefined Manipulators" .LP A \fImanipulator\fR may be used apparently as an inserted or extracted object, but many only change the state of the stream. See .BR manip "(3CC4) and " ios (3CC4) for more information. Several manipulators are predefined for use with ostreams. .TP .BI "ostr << " manip This is equivalent to the call \fImanip\fB(ostr)\fR. .TP .B "ostr << dec" This sets the conversion base of \fBostr\fR to 10. .TP .B "ostr << oct" This sets the conversion base of \fBostr\fR to 8. .TP .B "ostr << hex" This sets the conversion base of \fBostr\fR to 16. .TP .B "ostr << endl" This ends a line by inserting a newline and flushing \fBostr\fR. .TP .B "ostr << ends" This ends a string by inserting null (0) character into \fBostr\fR. .TP .B "ostr << flush" This is equivalent to calling \fBostr.flush()\fR. .\" .SH "SEE ALSO" .LP .na .BR ios.intro (3CC4), .BR ios (3CC4), .BR manip (3CC4), .BR sbufpub (3CC4), .TP .I C++ Library Reference .TP Chapter 3, "The Classic \fIiostream\fR Library", .TP Chapter 4, "Using Classic \fIiostream\fR in a Multithreaded Environment." .\" .TZ ????