ostream(3C++)

Synopsis

   #include <iostream.h>
   

   typedef long streamoff, streampos;
   class ios {
   public:
   	enum	seek_dir { beg, cur, end };
   	enum	open_mode { in, out, ate, app, trunc, nocreate, noreplace } ;
   	enum	{ skipws=01,
   		  left=02,  right=04, internal=010,
   		  dec=020, oct=040, hex=0100,
   		  showbase=0200, showpoint=0400, uppercase=01000, showpos=02000,
   		  scientific=04000, fixed=010000,
   		  unitbuf=020000, stdio=040000 };
   	// and lots of other stuff, see ios(3C++) ...
   } ;
   

   class ostream : public ios {
   public:
   		ostream(streambuf*);
   	ostream&	flush();
   	int	opfx();
   	ostream&	put(char);
   	ostream&	seekp(streampos);
   	ostream&	seekp(streamoff, seek_dir);
   	streampos	tellp();
   	ostream&	write(const char* ptr, int n);
   	ostream&	write(const unsigned char* ptr, int n);
   	ostream&	operator<<(const char*);
   	ostream&	operator<<(char);
   	ostream&	operator<<(short);
   	ostream&	operator<<(int);
   	ostream&	operator<<(long);
   	ostream&	operator<<(float);
   	ostream&	operator<<(double);
   	ostream&	operator<<(long double);
   	ostream&	operator<<(unsigned char);
   	ostream&	operator<<(unsigned short);
   	ostream&	operator<<(unsigned int);
   	ostream&	operator<<(unsigned long);
   	ostream&	operator<<(void*);
   	ostream&	operator<<(streambuf*);
   	ostream&	operator<<(ostream& (*)(ostream&));
   	ostream&	operator<<(ios& (*)(ios&));
   };
   

   class ostream_withassign : public ostream {
   		ostream_withassign();
   	ostream&	operator=(ostream&);
   	ostream&	operator=(streambuf*);
   	ostream_withassign&	operator=(ostream_withassign&);
   };
   

   extern ostream_withassign cout;
   extern ostream_withassign cerr;
   extern ostream_withassign clog;
   

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

Description

In the following descriptions, assume:
-- outs is an ostream.
-- outswa is an ostream_withassign.
-- outsp is an ostream*.
-- c is a char.
-- ptr is a char* or unsigned char*.
-- sb is a streambuf*
-- i and n are ints.
-- pos is a streampos.
-- off is a streamoff.
-- dir is a seek_dir.
-- manip is a function with type ostream& (*)(ostream&).

Constructors and assignment:

ostream(sb)

Initializes ios state variables and associates buffer sb with the ostream.

ostream_withassign()

Does no initialization. This allows a file static variable of this type (cout, for example) to be used before it is constructed, provided it is assigned to first.

outswa=sb

Associates sb with swa and initializes the entire state of outswa.

inswa=ins

Associates ins->rdbuf() with swa and initializes the entire state of outswa.

Output prefix function:

i=outs.opfx()

If outs's error state is nonzero, returns immediately. If outs.tie() is non-null, it is flushed. Returns non-zero except when outs's error state is nonzero.

Output suffix function:

osfx()

Performs ``suffix'' actions before returning from inserters. If ios::unitbuf is set, osfx() flushes the ostream. If ios::stdio is set, osfx() flushes stdout and stderr.

osfx() is called by all predefined inserters, and should be called by user-defined inserters as well, after any direct manipulation of the streambuf. It is not called by the binary output functions.

Formatted output functions (inserters):

outs<<x

First calls outs.opfx() and if that returns 0, does nothing. Otherwise inserts a sequence of characters representing x into outs.rdbuf(). Errors are indicated by setting the error state of outs. outs is always returned.

x is converted into a sequence of characters (its representation) according to rules that depend on x's type and outs's format state flags and variables (see ios(3C++)). Inserters are defined for the following types, with conversion rules as described below:

char*

The representation is the sequence of characters up to (but not including) the terminating null of the string x points at.

any integral type except char and unsigned char

If x is positive the representation contains a sequence of decimal, octal, or hexadecimal digits with no leading zeros according to whether ios::dec, ios::oct, or ios::hex, respectively, is set in ios's format flags. If none of those flags are set, conversion defaults to decimal. If x is zero, the representation is a single zero character(0). If x is negative, decimal conversion converts it to a minus sign (-) followed by decimal digits. If x is positive and ios::showpos is set, decimal conversion converts it to a plus sign (+) followed by decimal digits. The other conversions treat all values as unsigned. If ios::showbase is set in ios's format flags, the hexadecimal representation contains 0x before the hexadecimal digits, or 0X if ios::uppercase is set. If ios::showbase is set, the octal representation contains a leading 0.

void*

Pointers are converted to integral values and then converted to hexadecimal numbers as if ios::showbase were set.

float, double, long double

The arguments are converted according to the current values of outs.precision(), outs.width() and outs's format flags ios::scientific, ios::fixed, and ios::uppercase. (See ios(3C++).) The default value for outs.precision() is 6. If neither ios::scientific nor ios::fixed is set, either fixed or scientific notation is chosen for the representation, depending on the value of x.

char, unsigned char

No special conversion is necessary.

After the representation is determined, padding occurs. If outs.width() is greater than 0 and the representation contains fewer than outs.width() characters, then enough outs.fill() characters are added to bring the total number of characters to ios.width(). If ios::left is set in ios's format flags, the sequence is left-adjusted, that is, characters are added after the characters determined above. If ios::right is set, the padding is added before the characters determined above. If ios::internal is set, the padding is added after any leading sign or base indication and before the characters that represent the value. ios.width() is reset to 0, but all other format variables are unchanged. The resulting sequence (padding plus representation) is inserted into outs.rdbuf().

outs<<sb

If outs.opfx() returns non-zero, the sequence of characters that can be fetched from sb are inserted into outs.rdbuf(). Insertion stops when no more characters can be fetched from sb. No padding is performed. Always returns outs.

Unformatted output functions:

outsp=&outs.put(c)

Inserts c into outs.rdbuf(). Sets the error state if the insertion fails.

outsp=&outs.write(s,n)

Inserts the n characters starting at s into outs.rdbuf(). These characters may include zeros (i.e., s need not be a null terminated string).

Other member functions:

outsp=&outs.flush()

Storing characters into a streambuf does not always cause them to be consumed (e.g., written to the external file) immediately. flush() causes any characters that may have been stored but not yet consumed to be consumed by calling outs.rdbuf()->sync.

outs<<manip

Equivalent to manip(outs). Syntactically this looks like an insertion operation, but semantically it does an arbitrary operation rather than converting manip to a sequence of characters as do the insertion operators. Predefined manipulators are described below.

Positioning functions:

outsp=&ins.seekp(off,dir)

Repositions outs.rdbuf()'s put pointer. See streambuf_pub(3C++) for a discussion of positioning.

outsp=&outs.seekp(pos)

Repositions outs.rdbuf()'s put pointer. See streambuf_pub(3C++) for a discussion of positioning.

pos=outs.tellp()

The current position of outs.rdbuf()'s put pointer. See streambuf_pub(3C++) for a discussion of positioning.

Manipulators:

outs<<endl

Ends a line by inserting a newline character and flushing.

outs<<ends

Ends a string by inserting a null (0) character.

outs<<flush

Flushes outs.

outs<<dec

Sets the conversion base format flag to 10. See ios(3C++).

outs<<hex

Sets the conversion base format flag to 16. See ios(3C++).

outs<<oct

Sets the conversion base format flag to 8. See ios(3C++).

References