*************************************************************************
   *************************************************************************
   **                                                                     **
   **                   ----====  KPlib v1.4.2 ====----                   **
   **                                                                     **
   **                         a C++ Class Library                         **
   **                                                                     **
   **                          by Keith Pomakis                           **
   **                          pomakis@pobox.com                          **
   **                                                                     **
   **          Released to the public domain on October 10, 1994          **
   **                   Last updated on March 30, 1999                    **
   **                                                                     **
   *************************************************************************
   *************************************************************************

                           ****  Documentation  ****


****************************************************************************
PURPOSE AND HISTORY
****************************************************************************

I know what you're saying to yourself:  "What, another class library?".
Yup, that's exactly what this is.  My thesis work required me to do a lot
of C++ programming.  The availability of a good class library was
essential to my work.  However, I didn't want to use any compiler-specific
class libraries because I wanted to insure that my code was portable.  I
didn't want to use a third-party class library for two reasons.  First,  I
couldn't find anything out there that satisfied me, and second, even if I
did, I'd hate the prospect of having to drag around third-party software
with me wherever I went.  I'd rather be my own technical support.  So I
wrote this class library and it has served me very well.  I don't know
how I would have survived without it.  It is my hope that, in distributing
this library, others will be able to use what I've put together to increase
their own programming productivity.

Unfortunately, I have had no time to develop a good user's manual for the
library.  Furthermore, I haven't had the opportunity to test the library on
a compiler other than g++ 2.6.x and g++ 2.7.x (although I've heard that it
also compiles well under CodeWarrior for the Macintosh and Watcom C++ 10.5
under DOS4GW-DOS).  Since C++ was in its pre-standard days when I wrote the
library, it wouldn't surprise me if some C++ compilers fail to compile it.
I'm pretty confident that it should compile on most C++ compilers though,
since I paid a lot of attention to the draft standard while writing it.

As far as the user's manual goes, I believe that the library is fairly
intuitive and self-explanatory.  A programmer should be able to understand
how to use the library merely by perusing the "*.h" files.

Perhaps a good user's manual will be a future project of mine.

Version 1.4.2: March 30, 1999:
    - Fixed a couple of tiny little things to keep the library up to date
      with the newest compilers.  Thanks to Brian May (bmay@pobox.com) for
      pointing these things out.

Version 1.4.1: May 12, 1996:
    - Fixed KPSortableList<T>::sort() so that it handles empty lists
      correctly.  Thanks to Peter Westerstrom (md3peter@mdstud.chalmers.se)
      for pointing this bug out.

Version 1.4.0: March 2, 1996:
    - Added superset and subset functions to KPSet<T> (finally!).
    - Got rid of the silly explicit instantiations of the swap() function
      template for intrinsic data types in "KPbasic.h".
    - Made simulation of the bool data type easier (for use with those
      compilers that haven't caught up with the standard yet) by adding
      the option of defining the KP_SIMULATE_BOOL symbol.
    - Did a bit of fine-tuning.

Version 1.3.6: February 11, 1996:
    - Made KPList::operator+() and KPList::operator-() functions const
      correct.
    - Added option of defining the NO_KPLIST symbol when using KPString to
      avoid unnecessary instantiation of KPList<KPString>.
    - Removed maximum length restrictions from KPString stream functions,
      i.e., operator>>(), read_line() and read_token().  In other words,
      arbitrarily long strings can now be read in!

Version 1.3.5: December 12, 1995:
    - Fixed bug in KPBag<T>::operator KPList<T>() const.  Thanks to Manuel
      Ornato (ornato@onera.fr) for pointing this bug out.

Version 1.3.4: November 6, 1995:
    - Fixed bug in KPStack<T>::clear().  Thanks to Gilbert Ramirez Jr.
      (gram@merece.uthscsa.edu) for pointing this bug out.

Version 1.3.3: August 8, 1995:
    - Fixed bug in KPSet<T>::operator-().

Version 1.3.2: July 10, 1995:
    - Modified KPArray::operator=() to be more efficient when the source
      and destination arrays are of the same size.
    - Added KPPriorityQueue<T>::contains() and
      KPPriorityQueue<T>::occurrences_of().
    - Thanks to Timo Eloranta (sttiel@uta.fi) for suggesting these changes.

Version 1.3.1: April 25, 1995:
    - Made various minor changes to increase compiler compatibility and
      improve efficiency.

Version 1.3.0: April 22, 1995:
    - Sealed a memory leak in KPIterator<T>::remove_current().
    - Changed the return type of KPIterator<T>::remove_current() to void.
    - Added KPSet<T>::operator<() so that sets of sets are possible.
    - Added KPBag<T> class.

Version 1.2.2: January 6, 1995:
    - Fixed bug in KPQueue<T>::clear() function.
    - Removed problematic operator<<(KPString&, const T&) function.
    - Added discussion of explicit template instantiation to documentation.

Version 1.2.1: November 7, 1994:
    - Fixed a couple of non-g++ incompatibilities, bringing the library
      a little closer to be compilable on other compilers.

Version 1.2: October 21, 1994:
    - Modified inline max and min functions in KPbasic.h to make them more
      general.
    - made several KPSet functions "const" correct.

Version 1.1: October 12, 1994
    - Appended prefix "KP" to class and file names to avoid name clashes
      with existing libraries.
    - Fleshed document out a little more.

Version 1.0: October 10, 1994
    - First release into the public domain.
    - Not actually labelled with a version number.


****************************************************************************
DISCLAIMER
****************************************************************************

I am releasing this library to the public domain.  Therefore, people can use
it, copy it, distribute it, modify it, and do whatever they want with it.

Although this library has been well thought out, tested, and used in real
applications, it is not guaranteed to be bug-free.  Therefore, I am not
responsible for anything that happens, either directly or indirectly, due to
the usage of this library.

If you modify or add to this library in any way, I'd appreciate it if you
dropped me a line (or Internet packet, whatever) telling me what you did.
I'm always interested in potential improvements to my work!

Also, if you find any bugs (gasp!) or have any questions or comments about
the library, you can contact me as well.  My e-mail address is
"pomakis@pobox.com".  I'd be interested in hearing what you think!

Oh, one other thing... I've put a lot of work into this library, so I'd
appreciate it if you kept my name attached to it when distributing or
modifying it.


****************************************************************************
REQUIREMENTS AND COMPATIBILITY
****************************************************************************

This library has been successfully compiled with GNU g++ versions 2.6.x and
2.7.x, Metrowerks CodeWarrior for the Macintosh, and Watcom C++ 10.5 under
DOS4GW-DOS.  I cannot guarantee that it will compile on other C++
compilers.  However, I tried to keep it as "standard" as possible, so I am
hopeful.

The library uses templates quite heavily, but does not make use of exception
handling.

In order for the template classes in this library to successfully link with
your projects using g++ 2.6.x or g++ 2.7.x, the command-line option
"-fno-implicit-templates" should be used, and all required template classes
and functions should be explicitly instantiated.  Unfortunately, this may
also require the instantiations of templates that are indirectly used, such
as the base classes of the classes being used.  Fortunately, the list of
undefined symbols at link time will provide you with the names of the
templates that need instantiations.  Unfortunately, this list is mangled.
Fortunately, there are demanglers out there.  Unfortunately, I'm not going
to tell you where.  Fortunately, this entire problem should go away in
g++ 2.8.x (at least I HOPE so; they SAID that version 2.7.0 was going to
fix the problem... so much for that!).


****************************************************************************
CONTENTS
****************************************************************************

The library consists of the following classes:

    KPList<T>
        A two-way list that assumes nothing about its elements except they
        correctly implement a default constructor and operator=().

    KPComparableList<T>
        A subclass of KPList<T> which also assumes its elements can be
        compared with operator==(), thus providing more powerful methods.

    KPSortableList<T>
        A subclass of KPComparableList<T> which also assumes its elements
        can be compared with operator<(), thus providing more powerful
        methods.

    KPReadOnlyIterator<T>
        An iterator with pointer-like semantics which can iterate over any
        of the above lists for reading purposes only.

    KPIterator<T>
        An iterator with pointer-like semantics which can iterate over any
        of the above lists for the purpose of reading, modifying, deleting,
        or adding elements to or from arbitrary locations in the list.

    KPArray<T>
        A dynamically-sizable array that assumes nothing about its
        elements except they correctly implement a default constructor
        and operator=().

    KPComparableArray<T>
        A subclass of KPArray<T> which also assumes its elements can be
        compared with operator==(), thus providing more powerful methods.

    KPSortableArray<T>
        A subclass of KPComparableArray<T> which also assumes its elements
        can be compared with operator<(), thus providing more powerful
        methods.

    KPQueue<T>
        A queue that assumes nothing about its elements except they
        correctly implement a default constructor and operator=().

    KPPriorityQueue<T>
        A priority queue that assumes its elements correctly implement
        a default constructor, operator=(), operator==() and operator<().

    KPStack<T>
        A stack that assumes nothing about its elements except they
        correctly implement a default constructor and operator=().

    KPSet<T>
        A set that assumes its elements correctly implement a default
        constructor, operator=(), operator==() and operator<().  All
        union, intersection, difference and superset/subset operations
        are of order O(n).

    KPBag<T>
        A bag that assumes its elements correctly implement a default
        constructor, operator=(), operator==() and operator<().

    KPString
        A string class which implements basic string functions and more
        (such as tokenizing methods which return KPList<KPString>).  This
        class uses reference counting and copy-on-write semantics to
        insure that it as efficient as possible.


****************************************************************************
USAGE
****************************************************************************

The library consists of the following files:

        KPArray.h
        KPBag.h
        KPList.h
        KPPriorityQueue.h
        KPQueue.h
        KPSet.h
        KPStack.h
        KPString.cxx
        KPString.h
        KPbasic.h

These files should be kept together in a single directory.  The name of each
file directly represents what one would expect of its contents.  The file
"KPbasic.h" contains a few basic functions and definitions that you might
find convenient.

All of the classes in this library, except for KPString, are template
classes.  Therefore, it easy to use these classes with your own classes as
well as with all of the predefined data types.  The classes were not written
to be easily derived from.

"KPString.cxx" is the only source file of the library.  In order to use this
class it will have to be compiled with the rest of your code.  See the
files in the accompanying "sample_progs" directory to see how this can be
done conveniently.  Alternatively, "KPString.cxx" can be precompiled and
converted to a library archive for standard linking.

See section "REQUIREMENTS AND COMPATIBILITY" for a discussion of explicit
template instantiation and the g++ "-fno-implicit-templates" option.

Since I haven't actually written a user's guide for this library, the "*.h"
files will have to suffice as documentation.

That's about it.  Enjoy!


.--------------------+--------------------------------------------.
| Keith Pomakis      | Don't take life too seriously.             |
| pomakis@pobox.com  | After all, you'll never make it out alive. |
+--------------------+--------------------------------------------+
|         WWW home page: "http://www.pobox.com/~pomakis/"         |
`-----------------------------------------------------------------'