PROLOGUE --------

This tutorial started out as a "small" example of how to interface an I/O
object into the AT&T iostream classes currently provided with almost every
C++ compiler. When I say "small", I mean just that - but the scope of the
information I wanted to present really didn't fit well into that little hole,
so it turned out a little larger than I had initially hoped. However, I think
the effort was worth it - I know it was for me, since although I've done code
which deals with ostream, I hadn't fooled at all with istream derived
facilities, and learned some new things in the process.

I can't really cite any single reference on iostreams that might prove useful
for those wanting to go further other than the AT&T iostreams reference
manual (my copy is out on loan at the moment so I can't quote the ISBN
number). I have never come across one which is more complete than this
reference, and most other references (including documentation from MSC/C++C,
Borland, IBM etc.) tend to quote from it fairly liberally, but lack any of
the important information needed to put it all together. While Microsoft's
C++ tutorial reference has some great hints for getting started in iostream
manipulators, it lacks in providing any information on interfacing to the
iostream classes themselves.

Hopefully the information I've provided below will make some sense. It is as
complete as I could make it without really going overboard. Most of the
ostream related code is gleaned from my own library, but the rest is brand
new.

The text of this tutorial and the accompanying source code are donated to the
public domain.


Tutorial in iostreams ---------------------

This little project started out with the following aims:

A)  To define a simple input/output object, one that consumes bytes sent to
    it and generates data for input into a sample program. It should there-
    fore feature a "read" and "write" function.  The object created is simply
    a loopback buffer - input is queued immediately for output in FIFO (first
    in first out) fashion.

B)  To create a streams interface for this object, so that existing facili-
    ties for I/O in the AT&T streams classes can be used directly in a
    polymorphic fashion (ie. make use of C++ inheritance & virtual dispatch).

    Specifically, I wanted to demonstrate the following aspects of iostreams:

    - Use of buffered vs. unbuffered I/O

    - Using the streams buffer for both input and output operations.  (an
      interface to iostream, rather than just istream or ostream)

    - How the put, get and putback buffers work

C)  To write a trivial application which uses both components and provide a
    means of interactively demonstrating how it all works.


A - The I/O Object ----------------

class Myio;

This class is simply a front-end for a circular buffer. Input bytes are added
at the head, and read from the tail. It is fixed in size, set by the
constructor.

Two read/write functions are provided to access any contained data:

    int Myio::read (char * buf, int max);
    int Myio::write (char const * buf, int len);

These are both non-blocking calls which return the number of bytes read or
written. They know nothing about line delineation - only about raw bytes, as
would be the case for almost any I/O device.

In addition, an internal flag is maintained to indicate when a write results
in a buffer 'overflow' (an attempt to write more bytes than will fit in the
buffer) and 'underflow' (an attempt to read an empty buffer). These flags
reflect the last write and read calls respectively, and are reset or set on
each write or read call.  The members Myio::readok() and Myio::writeok()
rturn the settings as a boolean value.

A Myio object can also optionally create a stream. It is created and comes
into life when the member function Myio::stream() is called. If it was
previously created, this function simply returns a reference to the existing
stream. The stream, if it exists, is deleted by the destructor.

Myio's stream is an iostream, which inherits all of the abilities of both
ostream (for output) and istream (for input), including all operators. This,
of course, is the primary benefit of using streams!


B -  The Streams Interface -----------------------

class Mystreambuf; class Mystreambase; class Mystream;

Three classes as above are used. Mystreambuf derives from streambuf, and is
responsible for the input output operations and buffering on behalf of a Myio
object.  Mystreambase is used as a base class for Mystream to assist in the
initialisation of the (My)streambuf passed to the iostream constructor.

The iostream side is in fact very simple. Nothing really needs to be
overridden, and all of the work is done in Mystreambuf, where all the action
really takes place.

The relationship between the ios/stream classes and the streambuf family is
one of delegation rather than inheritance. The user/application accesses
streambuf I/O via the stream object, not directly.  A class diagram showing
the basic iostream classes and our classes would look like:


         _ istream _ / \ ios -- ostream -- iostream \ \ \ Mystream \_____
Mystreambase _/ | | (owns) | streambuf -- Mystreambuf


All relationships, except the one marked "(owns)", indicate inheritance. The
'owns' relationship is where the delegation occurs.  ios is inherited
virtually, so that there is only one combined 'ios' object at the root of the
streams inheritence tree.

Within Mystreambuf, we need to override the functions responsible for actual
input and output.  But first, let's discuss how this streambuf works.

Mystreambuf uses a single buffer, using the default buffer size allocated for
any streambuf (under most operating systems, this will be 1024 bytes). Since
we are dealing with both input and output operations, and these operations
are independent so far as the streambuf is concerned (as is the case with,
for example, serial I/O, but *not* the case with files), the buffer is split
into two; the first half is used for writing, the second for reading.

The buffer used for writing is called the "put" buffer. Nothing mysterious
there - when full, streambuf::overflow() function is called, and via virtual
dispatch calls our Mystreambuf::overflow() which takes the contents of the
buffer and writes it to the output device.

The read - or "get" - buffer is slightly more complex. There are occasions in
dealing with an input stream where it is convenient to know what's next
without actually removing it from the stream.  That way, you can use the next
character as an indication of what to do next. For example, if you're parsing
a number, you want to know whether or not the next character is a valid
digit, and stop parsing if it isn't. The read side therefore incorporates the
idea of a "putback" buffer - after being read, the character can be placed
back into the input stream.

The putback buffer is entirely the responsibility of any streambuf derived
class. It most you need to support a one character putback buffer - it is not
valid to remove, and then restore, more than one character from the stream.
It is also not valid put 'putback' any character but the one that was the
result of the last 'get'.  It really must be "put back", not any old
character "pushed" (you could actually support 'pushing' data into the stream
if you wanted to, but you shouldn't use putback to do it).

The get buffer is set up as:

    Offset 0 1 2 3 ....  n | | | | to end of buffer |
+---+---+---+---------------------+ ^ ^ | +- Start of get buffer (where data
is read in) | +- Where data is putback

Each time streambuf runs out of characters to give to its client, the
underflow() function is called. This fills the get buffer (get buffer size -
1, starting at offset 1) and reserves the first byte in case the previously
read character needs to be put back.

streambuf provides internal pointers into the put, get and putback areas. All
of the I/O functions it provides handle these automatically. In our
underflow() and overflow() functions, we need to set these pointers according
to where and how much data is read in.

I mentioned above that in our case, the input & output streams are
independant. That's not entirely the case - it may happen that when reading
from the Myio buffer we run out of data and need additional data in the
output stream buffer not yet written to Myio. We therefore flush the output
stream before retrieving any data by calling overflow() directly from within
underflow().

The sync() function is also overridden. This simply empties all buffers by
flushing the output buffer and discarding any buffered input.


C - The Application -----------------

The application itself is a simple menu, offering choice to send a line of
output to the IO object (via its stream), read one in, and dump/display
information both about the stream and Myio object.

This added two other classes to the project:

    - myApplication: the actual application, implemented as a class.  The
      only way to go in C++. :-)

    - myList: a simple line input class, whose sole purpose in life is to
      extract a linefeed delimited line from any istream object and return it
	as a char const *.  (I posted this code last week, but have since fixed
	one minor bug I found in the process of developing Myio).

A couple of subtle points - class myApplication uses a pointer to member
function it its menu selection. This is not the only way of doing this of
course, but I thought it was a good way of demonstrating a very C++ specific
concept, operator ->*, which does not exist at all in C.

Additional notes are included in the source comments.


Making the application ----------------------

Hopefully this is a fairly simple thing to do - just compile the modules:

    Myiodemo.cpp Myio.cpp Mystream.cpp myLine.cpp

and link them together. A simple makefile is provided - take a look at the
definitions at the top, adjust as desired, and type "make" (or nmake). If you
use any of Borland's compilers, just add the above files to a new project
called "Myiodemo.PRJ", set it to produce a .EXE (*not* Windows or PM based)
and press F9.

Assuming a C++ compiler compatibile with cfront 2.1 and the presence of an
iostreans 1.2 library, the only non-portable part of this app is the use of
getch() from conio.h. This isn't easily provided under a UNIX system. You can
either fudge it by writing a getch() which switches into/out of 'raw' mode,
or use getchar() and clear everything up to and including a CR or NL after
the first character (the user still has to hit CR for input to get to the
program).



EPILOGUE --------

Just some notes as to use of this code. If you need an output or input only
class, then you use ostream or istream wherever iostream is mentioned in this
example.  Also, if you use buffered mode (you can support it or not - you can
even ignore the streambuf setting at your discretion), then you can use the
entire buffer rather than just half each for input output.

If you interface to an input only object, you only need to override
streambuf::underflow(). Conversely, you override streambuf::overflow() for an
output only object. I have noticed that *some* implementations of iostreams
define the overflow() and underflow() methods as pure virtual functions,
whereas the AT&T default defines each as simply returning EOF.

If portability is any concern, you may need to override the function you
aren't using in this fashion. The default sync() simply returns 0 (success),
but again, this is sometimes defined as a pure virtual, so you may need to
define it in your implementation.

In some cases, you may wish to "switch" between unbuffered and buffered
modes. This is easily done by defining a function in Mystream which does it,
and this object is of course accessible in your I/O object (in this case
Myio). The only thing you need to remember is to flush all the buffers by
calling sync() when switching from buffered to unbuffered mode.

Note also that some streambuf constructors take an existing buffer. This
means that you can use buffers already provided in your I/O object directly
rather than being forced to "double buffer" anything.  Your buffer can also
be any size you like, subject to memory and other architecture constraints.


Enjoy!

David Nugent - 3:632/348@fidonet.org
Moderor ('93-'94) of the FidoNet international C++ EchoMail conference