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