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

Stream Control - Class ios

   The IOStreams library was first published by AT&T as part of the version
   2.0 release of their C++ compiler Cfront. A modified version has been
   submitted to the ANSI committee to be considered for inclusion into the
   C++ standard. The standardization process is not yet completed, but this
   implementation of IOStreams is as close as practicable to that presented
   to the ANSI committee.


   Input and output streams have features in common, including the need to
   keep track of errors, control details of representation of numbers, the
   treatment of whitespace and padding etc.

   Class ios is a base class that provides this sort of functionality, from

   which input and output classes (istream, ostream and iostream) are
   derived.

   The error handling features are particularly important. Three classes or
   error are noted, described as eof, fail, and bad.

   1. End of file (eof) errors indicate that no further characters could be
   sent to or got from the associated stream.

   2. Errors classed as fail mean that the particular operation attempted
   was unsucessful, but generally that use of the stream can continue once
   the error has been cleared.

   3. Errors classed as bad probably mean that the stream is no longer
   usable.

   The public interface of class ios is as follows:

   class ios {public:
       enum io_state {

           goodbit=0,
           eofbit=1,
           failbit=2,
           badbit=4
       };

       enum relative_to {
           beg,
           cur,
           end
       };

   // The following enumeration applies to file
   // related streams
       enum open_mode {
           in=0x1,
           out=0x2,
           ate=0x4,
           app=0x8,
           trunc=0x10,

           nocreate=0x20,
           noreplace=0x40,
           translated = 0x80
       };

       enum format_mode {
           skipws = 0x1,
           left = 0x2,
           right = 0x4,
           internal = 0x8,
           dec = 0x10,
           oct = 0x20,
           hex = 0x40,
           showbase = 0x80,
           showpoint = 0x100,
           uppercase = 0x200,
           showpos = 0x400,
           scientific = 0x800,
           fixed = 0x1000,
           unitbuf = 0x2000,

           stdio = 0x4000,
       };

       static const long stickywidth;  // = 0x8000
       static const long spacing;          // = 0x10000

   // Format bit sets
       enum format_mode_mask {
           basefield = dec|oct|hex,
           adjustfield = left|right|internal,
           floatfield = scientific|fixed
       };

   // Constructor & destructor
       ios(streambuf *buffer);
       virtual ~ios();

   // Functions to interrogate the error state
       int rdstate() const { return error_state; };


       int good() const;
       int eof() const;
       int fail() const;
       int bad() const;

       int operator!() const;
       operator void*();

   // Set the error state
       void clear(int = 0);

   // Set/ read the fill character
       char fill(char);
       char fill() const;

   // Set/ read floating point precision
       int precision(int);
       int precision() const;

   // Set/ read a tied output stream

       ostream *tie(ostream*);
       ostream *tie() const;

   // Set/ read the format flags
       long flags(long);
       long flags() const;
       long setf(long bits_to_set, long mask = 0);
       long unsetf(long bits_to_clear);

   // Set/ read a field width
       int width(int);
       int width() const;

   // Other utilities

       streambuf *rdbuf() const;

       static void sync_with_stdio();

       static int bitalloc();


       static int xalloc();

       long &iword(int index);
       void* &pword(int index);
   };

   The enum io_state is used when the state of the stream is to be reported:

   goodbit          No errors - everything ok!

   eofbit           Normally set when there is a genuine end of file
                    condition.

   failbit          An error has ocurred, but is probably recoverable. The
                    stream is still in a useable state

   badbit           An error has occurred such that the stream is not suitable
                    for further use.



   The enum relative_to contains values used when moving the stream (file)
   pointer within a stream:

   beg              For seek operations relative to the beginning of the
                    stream (file)

   cur              relative to the current position in the stream (file)

   end              relative to the end of the stream (file)


   The enumeration open_mode applies to file related streams:

   in               Input allowed.

   out              Output allowed.

   ate              A seek to the end of the file to be performed during open.


   app              All writes are to the end of  the file - implies out.

   trunc            Existing contents of the file to be discarded. Implies out
                    unless ate or app specified as well.

   nocreate         Open will fail if the file does not already exist

   noreplace        Open will fail if the file does already exist

   translated       CR/LF pairs to be translated to newline characters on
                    input and newline characters to be translated to CR/LF
                    pairs on output (the normal behavior for MS-DOS and
                    OS/2)


   The enum format_mode is used in selecting stream formatting:

   skipws           Skip past leading white space when extracting.

   left             Left-adjust values when inserting (fill on the right).


   right            Right-adjust values when inserting (fill on the left).

   internal         When inserting, fill between the numeric sign or base
                    indicator and the value.

   dec, oct, hex    Default radix for integers. If none specified, default is
                    decimal and normal C++ conventions will be respected on
                    input, as per showbase.

   showbase         If this is set, base-16 numbers will be inserted with a
                    leading "0x", and base-8 numbers will have a leading
                    zero.

   showpoint        If this is set, the floating-point inserters will print a
                    decimal point and trailing zeroes, even when the
                    trailing places are not significant.

   uppercase        If this is set, "E" instead of "e" will be used to
                    indicate the exponent of a floating point number, and

                    "A" through "F" will be used to represent hex digits
                    instead of "a" through "f". If uppercase and showbase
                    are both set, the string "0X" instead of "0x" will be
                    used to indicate a base-16 number.

   showpos          If this is set, positive numbers will be inserted with a
                    leading "+".

   scientific       If this is set, the floating-point inserters will print a
                    number with one digit before the decimal point, and the
                    number of digits after the decimal point equal to the
                    value of precision(). The character "e" will introduce
                    the exponent.

   fixed            If this is set, the floating-point inserters will use
                    precision() to determine the number of digits after the
                    decimal point. 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 zeroes to show the

                    decimal place explicitly.

   unitbuf          When this is set, a flush is performed after each
                    insertion.

   stdio            When this is set, streams using stdiobufs will flush
                    stdout and stderr after each insertion.


   Field width settings usually lapse after each output operation, this
   format bit makes them persistent:

       static const long stickywidth;  // = 0x8000

   This format bit causes insertion of a single space after each item output
   except the endl manipulator (see later):

       static const long spacing;      // = 0x10000

   The format bit sets in the enum format_mode_mask allow the the control of

   formatting in a logical manner:

       basefield       = dec|oct|hex,
       adjustfield     = left|right|internal,
       floatfield      = scientific|fixed

   Class ios is a virtual base class for ostreams, istreams and iostreams,
   so any of the following functions can be called for objects of any of
   these types, or types derived from them.

   All functions described here require the inclusion of iostream.hpp or
   some header file that itself includes iostream.hpp.