5/10/93
Windows Tech Journal
OOP Alley, July 1993
Greg Voss

Introduction to Collections in C++, Part II

  o Source code for DiskTutor/NIH collection class library
  o Example programs from June and July Listings
  o Verification suite
       

Usage Notes
===========

Recommended root directory: c:\dt
Use pkunzip with -d option to unzip archive. 
Compiled with Borland C++ 3.1 and Microsoft C/C++ 7.0.

Each directory has a makefile for both BC++ and MSC:

    BC++    makefile
    MSC     msc70.mak

With BC++ use make.exe, with MSC use
nmake.exe.  Also note that when make.exe
is invoked without specifiying a filename,
it assumes it will be reading from makefile.
If you are compiling with MSC, you must
tell nmake the name of the makefile:

    make all                    # BC++
    nmake /f msc70.mak all      # MSC

This archive contains library source,
test suites, and example programs for
June and July columns.  Similar code
was posted in June, but the June code
did not support compilation with MSC.
All code supplied in June is supplied
here so you don't need to keep the
June archive if you have this one.
In addition this archive has the examples
for the July '93 column.

This collection class library 
is basically Keith Gorlen's original
NIH class library scaled down to fit
comfortably within a DOS small memory
model.  It has also been simplified with
an eye toward teaching collection classes
rather than taking the everything-but-the-
kitchen-sink approach.

The original version of the DiskTutor class library
was compiled with Turbo C++ 2.0 in June of 1990
and was distributed with Turbo C++ DiskTutor--
a book that came packaged with a streamlined version
of Borland's C++ compiler.  Revisions were made to
make the code compatible with the more strict error
checking implemented by BC++ 3.1.  Large model
compilation has not been tested since June 1990.
There are some tricky issues for large model
compilation dealing with pointers
(see dtlib\oopsconf.h).

The current version compiles without generating
warning messages or errors.  There are four
basic directories you need to deal with:

    dt\dtlib        library source
    dt\dtlibv       verification suite
    dt\jun93        OOP Alley Listings for June '93
    dt\jul93        OOP Alley Listings for July '93

The verification suite now works under DOS for
both BC++, and MSC.  The DOS version is sligtly
more complicated because of occasional errors
that occured when piping output from test
programs into diff.  A public domain version of
diff.exe has been included in dt\dtlibv.
See instructions in the makefiles in dt\dtlibv
to invoke test suites.  Also note that it is
possible for test program output to vary slightly 
under certain conditions without indicating
an error.  

For example, because the Dictionary
class is derived from Set, Dictionary objects
do not guarantee the order of their elements.
Tests involving Sets, and Bags should take
the possibility of random ordering into
account if you try to port this code to other
compilers.  However, for a given compiler,
the ordering of collection elements should be 
consistent unless the hashing algorithm or
memory models are changed.



Building the Library
====================

    1. Change to library directory
        >cd dtlib
    2. Compile  
        >make                           ## BC++
            or
        >make /f msc70.mak              ## MSC
    3. Install
        >make install                   ## BC++   
            or
        >make /f msc70.mak install      ## MSC

The last step will copy the header files to
../include and copy dt.lib (created in step 2
above) to ../lib


Compiling Examples
==================

    1. Change to example directory
        >cd jun93
            or
        >cd jul93
    2. Compile examples
        >make                           ## BC++
            or
        >make /f msc70.mak              ## MSC


Notes on Verification Suite
===========================

The programs in dtlibv automate verification of the library.
Only a fraction of the methods are actually tested, but
you can get an idea if something is grossly wrong with
the library by running the verification suite.

Converting the DiskTutor class library to compile
under MSC drove home the importance of verification
suites for me.  A number of bugs turned up that
would have been impossible to track down without
the verifcation suite.


Happy OOPing  -gmv
