-----------------------------------------------------------------------------
This library and associated documentation is:

Copyright  2001 - by Philip D. Howard - All rights reserved

Author/editor:  Phil Howard
-----------------------------------------------------------------------------

Name:           AVLMAP

Version:        0.10.2

Licensing:

As the author of the library, I reserve for myself all rights to the
library, including the right to change the licensing terms of future
versions.  This version is distributed according to the GNU Lesser
General Public License, in the version in effect at the time I did
this release, or the current version in effect at the time you choose
to use the current version.  The licensing applied to this version is
permanent; that is, the license of a future version, if different, will
not take away any rights attached to this version, including all copies
made of this version even after a newer version is released.

For more information see the file "LICENSE" or "lesser.txt" included
with this library, or http://www.gnu.org/copyleft/lesser.html


Description:

The AVLMAP library is a package consisting of two modules.  The AVL
module implements a low level AVL balanced binary tree, which supports
several features.  The MAP module implements a higher level mapping
abstraction, using the AVL module to store its data.

AVLMAP is written in C and is intended for C programmers.  It can be used
in C++ but C++ programmers will find that their usual ways of coding for
objects does not apply.  And this is because it is intended just for C.


Features:

- Mapping key/data types include:
    signed/unsigned int
    signed/unsigned long
    signed/unsigned long long
    double
    long double
    pointer
    array/string of signed/unsigned char
    array/string of signed/unsigned short
    array/string of signed/unsigned int
    array/string of signed/unsigned long
    array/string of signed/unsigned long long

- One mapping has the same key type, but each data value can vary
  in what data type it has.

- Mappings and AVL trees allow:
    forward/reverse increments
    first/last starting points
    access nearby element if exact not found
    duplicate elements of the same key (optional)

- AVL trees allow nodes to be shared between multiple trees.  This is
  done by means of a finite (one or more) number of keys in a node,
  each with its own set of link pointers to thread that node into a
  separate tree for each such key.


Installation:

The installation instructions are in file "INSTALL".  But if you are in
a hurry, you can just do:

    ./Configure --prefix=/usr/local
    make clean
    make install

You will probably have to configure your operating system to properly use
the new library.


Usage:

Once installed, usage is usually done by placing the appropriate include
statements in your C program (each module has one or more headers), coding
calls to the functions according to their documentation, and placing the
appropriate -L(directory) and -lh options on your gcc compilation, or the
equivalent for other compilers/linkers.

Documentation varies as this is still a package in a state of change.  Most
everything is documented in the source comments.  Some are heavily documented
with some HTML files and others have none at all.  For now, reading source
code is the best way.  Eventually there should be HTML files for everything
and possibly even man pages.


Porting:

I've tested this compilation and usage on Linux under Slackware and Redhat,
with the 2.2 and 2.4 kernels, and with glibc 2.1.1 and 2.1.3.  At one time
I had it also working on Sun Solaris 7, but have not tested it since making
a major number of changes.  I will be putting Solaris 7 back up, as well
as testing under FreeBSD and OpenBSD shortly.


Contributions:

I will be interested in contributions to the library, but additions to it
should follow a clean style and be well commented.  It is not necessary
to follow my styles if the contribution is a whole module.  But I will not
take uncommented or hard to read source code.

I will also be interested in packagings like DEB and RPM, and a BSD ports
setup, once I consider the library to be in pre-release status (the final
stage of beta testing).  At present the library is in ALPHA status since
it is not really complete.  It is, however, apparently functional on Linux
as I am already making use of it.


Warning:

This is a BETA release.  There probably are bugs.  Although the API design
should be stable at this point, new functions may still be added.


Contact:

Bug reports and other matters may be addressed to:  avlmap@ipal.org

-----------------------------------------------------------------------------
