lookup.c
--------

History
-------
26th October 1992  J R C  Started

   This module provides an extensible lookup table. The programmer interface
allows any number of entries to be added to a lookup table without needing
memory management to be done by the calling programme.

   There are functions

         |lookup_new| to create a lookup table;

         |lookup_delete| to dispose of an unwanted one;

         |lookup_insert| to add an entry to a table; and

         |lookup| to do the actual searching;

         |lookup_enumerate| to retrieve all the tokens currently in the
      lookup table.

   The interface allows for a hashing system to be used, providing that one
can be designed that allows for an extensible table: I have experimented
with this, but don't have such in a bug-free form at the moment.

   The module stores only a |void *| value for each entry in the table. This
would normally be a pointer (suitably cast) to some application-specific
data associated with the name. It is the applications responsibility to
ensure that if this pointer changes (because of flex movement, for example),
the value in the table is updated to refer to the new location of the data.
See the |resource| module for how this can be done in two different ways. It
relies on the fact that a |lookup_insert| of a value with a token already
known to the |lookup_| module will replace the previous value.

   The implementation of the lookup table is as an array of (char *, void*)
pairs, of a length which is a power of 2. When a table is filled, it is
|realloc|'d to the next power of 2. Pointers to tokens are held in the first
word of each array element, and the data pointer in the other half. This
allows only linear searching in the table; many improvements are possible
here, but have not been attempted. However, the interface specified here is
general enough to provide the facilities that are required without being
specific enough to prohibit the various abvious enhancements. The obvious
ones would be either

         hold the array sorted by token, cutting access time to O (log N),
      where N is the number of entries; or

         hash the token values, cutting access time to O (1).

   Unfortunately, one of |lookup_|'s clients makes use of a fact not
intended by its interface: this is that a call to |lookup_enumerate| returns
the tokens in the order they were inserted into the table. If this property
were to be maintained by either of these implementations, extra work would
be needed internally.

   (I do have a hashing implementation of the module, but it is not
bug-free.)
