2. The Hash Table Module

Whenever you need a cache or an associative array that must be independent of a particular display pointer then you should use the generic hash table mechanism within LESSTIF. Generally, it offers much better performance than a simple linked list, especially if there are many items to manage. The hash table mechanism makes reinventing the wheel unnecessary in almost every case.

You can think of a hash table as some kind of associative array. You first put a value named by an identifier into the hash table. Lateron you can ask for the value using the identifier. Both an identifier and its associated value make up an ``item''. The values and identifiers for the hash tables within LESSTIF are typedef'ed in a portable fashion:

LTHashItemIDLTHashItemValue

typedef XtPointer LTHashItemID;
typedef XtPointer LTHashItemValue;

This allows you to use the broad range of integral data types in C for both values and identifiers. And if the space provided by these data types isn't sufficient, you can use the identifiers and values as pointers to structures instead. Because of this broad range of data types you may have to provide functions for comparing two items and calculating a hash value of an item:

typedef unsigned int (*LTHashGetHashFunction)(LTHashItemID);
typedef Boolean (*LTHashCompareFunction)(LTHashItemID, LTHashItemID);

A LTHashGetHashFunction returns an unsigned integer that represents the hash value for that particular item specified as the parameter to the function. A LTHashCompareFunction must return True if the two items specified by the parameters are equal.

Hash tables are created and destroyed using the following two functions. You don't have to supply a size when creating a hash table because LESSTIF's hash tables grow as needed whenever new entries are added.

At any time you can ask a hash table how much items it currently contains.

After creating a hash table you can add (or remove) items to (from) it.