Click above to get retro games delivered to your door ever month!

ostream::operator<<

Usage

   #include <iostream.hpp>
   The prototypes of the inserter functions are shown in the public interface
   listing above.

Description

   The built-in inserters first call the inserter prefix function opfx(). If
   that returns zero, i.e. some error has occured, then the inserter does
   nothing. Otherwise it inserts a character sequence representing the
   argument object into the associated streambuf.

   If the operation fails the error flags will be set, in conceivable cases
   this will be because of an end of file condition returned by the
   associated streambuf, in which case the stream will no longer be usable,
   and the flags will be set to (ios::bad | ios::fail | ios::eof).

   The conversion process is controlled by the format flags and state
   variables of the ios part of the ostream object. For the built-in types
   this happens as follows:

   char

   No translation is performed.

   char *
   unsigned char *

   signed char *

   The sequence of characters that the pointer addresses, up to but not
   including the terminating '\0' character is translated as is, treating
   each element as type char.

   Integral types

   Translation is to a string of digits consisting of '0' - '7' if format
   flag ios::oct is set, '0' - '9' and 'a' - 'f' if ios::hex is set, or '0'
   - '9' otherwise. If ios::oct or ios::hex is set, the representation is of
   the argument as an unsigned value. Otherwise, if the argument is
   negative, a minus sign is generated. If the argument is positive, and the
   ios::showpos flag is set, a plus sign is generated.

   If the representation is octal or hex, and format flag ios::showbase is
   set, then octal values will be prefixed with a '0' character, and hex
   values will be prefixed with "0x", or with "0X" if the format flag
   ios::uppercase is set.

   The distinct types signed char and unsigned char are treated as byte wide
   integers, that is values in the ranges -128 to 127, and 0 to 255
   respectively.

   void *

   In the 16 bit compilers, pointers are translated to a four digit
   hexadecimal representation, as if ios::showbase were not set, in the S
   and M models (xxxx), or to a segment:offset representation (xxxx:xxxx) in
   the C, L, V and Z models or their equivalents. In the 32 bit compilers (X
   and P memory models) pointers are converted to int and then represented
   as if ios::hex and ios::showbase were set.

   float
   double
   long double

   If the ios::scientific format flag is set, the floating-point inserters
   will produce a representation with one digit before the decimal point,
   and a number of digits after the decimal point equal to the value of

   precision(). The character "e" will introduce the exponent, unless
   ios::uppercase is set in which case 'E' will be used.

   Extraneous trailing zeros, and, if there are no non-zero numbers after
   it, the decimal point also, are stripped unless ios::showpoint is set, in
   which case the decimal point and all trailing zeroes up to the precision
   are retained.

   If the ios::fixed format flag is set, the floating-point inserters will
   use precision() to determine the number of digits after the decimal
   point. Trailing zeros and the decimal point will be stripped unless
   ios::showpoint is set.

   Negative numbers will be preceded by a minus sign, and positive numbers
   by a plus sign only if ios::showpos is set.

   If neither scientific or fixed is set, numbers with exponents smaller
   than -4 or greater than precision() will be printed as if scientific were
   set. Other numbers will be printed using zeros as required to show the
   decimal point explicitly.

   streambuf &

   All the characters that can be extracted from the streambuf are sent
   without padding or translation to the ostream. This stops only when the
   source streambuf signals an end of file condition.

   The suffix function osfx() does not get called after this inserter.

   ostream &(*)(ostream &)
   ios &(*)(ios &)

   Pointers to functions of this particular form (pointer to function taking
   ostream reference argument, and returning ostream reference, and pointer
   to function taking ios reference argument, and returning ios reference)
   are treated specially. They act as parameterless manipulators; the
   operator<< function does not translate them into characters in the output
   stream, rather it has an effect on the ostream object involved.
   Manipulators of this sort are provided for most of the changes that can
   be made by appropriate setting of format state flags, specifically,  for

   ostream os:

   os << leftjust;
   os.setf(ios::left, ios::adjustfield);

   os << rightjust;
   os.setf(ios::right, ios::adjustfield);

   os << dec;
   os.setf(ios::dec, ios::basefield);

   os << oct;
   sets ios::oct similarly

   os << hex;
   etc

   os << showbase;
   os.setf(ios::showbase);

   os << showpoint;
   os.setf(ios::showpoint);

   os << uppercase;
   os.setf(ios::uppercase);

   os << fixed;
   os.setf(ios::fixed, ios::floatfield);

   os << scientific;
   os.setf(ios::scientific, ios::floatfield);

   os << floating;
   os.unsetf(ios::floatfield | ios::showpoint |
   ios::showpos);  (floating point defaults)

   os << stickywidth;
   os.setf(ios::stickywidth);

   os << spacing;

   os.setf(ios::spacing);

   os << defaults;
   sets os to default format flag values

   os << endl;
   Adds a newline and flushes

   os << ends;
   Null terminates a string

   These manipulators are implemented by providing functions like:

       ostream &leftjust(ostream &s)
       {
           s.setf(ios::left, ios::adjustfield);
           return s;
       }

       ios &dec(ios &s)

       {
           s.setf(ios::dec, ios::basefield);
           return s;
       }

   After the translation as above, if width() is non-zero, then padding
   takes place: fill() characters are added until the representation
   contains width() characters. If ios::left is set, the padding characters
   are added after the translated string. If ios::right is set they are
   added before the translated string (this is the default state of an
   ostream). If ios::internal is set, the padding is added after any sign
   information, or integer base information, but before the rest of the
   translation. Finally the ostream suffix function osfx() is called. User
   defined inserters should generally follow the spirit of these conversion
   rules, and in particular should call opfx() and osfx() in the same way.

Example 

   int i;
   double d;

   char *string;
   void *p;
   cout << spacing << i << d << string << p << endl;

Return Value

   Inserter functions must return a reference to the ostream into which the
   insertion was made.