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

   Streams: Buffer Classes
   class streambuf
   To  further understand how ostreams, and their equivalent input  class
   istreams, work we need to describe the class which provides  buffering
   for both input and output streams.

   The  streambuf class is also defined in file stream.hpp.  A  streambuf
   has functions to allow characters to be sent to and read from it and a
   pair  of  functions,  underflow and  overflow,  which  determine  what
   happens when the buffer associated with the streambuf is empty or full
   respectively.

   class streambuf
   {
   char *base;              // buffer, NULL if no buffer
   char *pptr;              // write pointer (1 past end of
                            // data in buffer)
   char *gptr;              // read pointer (next char to
                            // read), gptr chases pptr
   char *eptr;              // 1 past end of buffer
   int alloc;               // 1 if base was allocated
                            // using new

   int allocate();
   protected:
   FILE *fp;                // in case streambuf is just a
                            // layer over stdio
   streambuf *setbuf(char *buf, int buflen,
   int written = 0, int wasalloc = 0);
   public:


   // Functions for buffer full and empty respectively
   virtual int overflow(int c = EOF);
   virtual int underflow() { return EOF; }

   // Constructors
   streambuf();
   streambuf(char* buf, int buflen);

   // Destructor
   virtual ~streambuf();

   // Character by character functions
   int snextc()
   {return (gptr + 1 < pptr)
   ? (unsigned char) *++gptr
   : underflow();
   }

   int sgetc()
   {return (gptr < pptr)
   ? (unsigned char) *gptr
   : underflow();

   }

   int sputc(int c = EOF)
   {
   return fp
   ? putc(c,fp)
   : (pptr < eptr)
   ? (unsigned char) (*pptr++ = c)
   : overflow(c);
   }

   void sputbackc(char c)
   { (gptr > base) && (*--gptr = c) != 0; }

   // Access to buffer
   char *bufptr() { return base; }
   };

   The file pointer member of class streambuf is a programming compromise
   used  to  provide  synchronization of stdio  and  ostream  output.  It
   involves  an  extra test (in sputc) for each character  output,  so  a
   streambuf which was not tied to stdio would be significantly faster.

   The  overflow  and underflow functions are virtual,  so  that  derived
   streambuf   types  can  have  different  buffering   strategies.   The
   destructor  is also virtual, so that if derived streambuf objects  are
   created  and subsequently destroyed via a pointer to the  base  class,
   then an appropriate series of destructors is called.

   In  the  base class streambuf the buffer is a finite  sized  chunk  of
   memory,  either  provided via constructor arguments by  the  user,  or
   allocated dynamically. The overflow function can do no more than check
   if  there is a buffer.  If there is not, it will attempt  to  allocate
   one of 1024 bytes. If a buffer has already been allocated, the  buffer
   full  situation is final. No more can be done. The underflow  function
   simply returns end of file.

   Plain  streambuf  objects will typically be used  as  temporaries  for
   marshalling  or  consolidating a section of output before it  is  sent
   somewhere else.

   There  is  a  derivative of streambuf which  provides  more  permanent
   facilities: class filebuf.