HashTable

Overview

This class holds a collection of objects which are identified by integer key values. The HashTable object may expand to contain an increasing number of objects. It also supports several “iterator” functions, which are used to successively visit each object stored in the HashTable.

The functions associated with a HashTable object are the following:

• Define and query hashtable type
  • define() - Define suggested number of stored items
  • inquire() - Get current storage capacity
  • count() - Get number of contained objects
  • maxKey() - Get maximum key value
  • allKeys() - Get all key values
• Set and query elements
  • insert() - Place object at specified location
  • lookup() - Find object at specified location
  • remove() - Remove the object from specified location
  • clear() - Remove all objects from the HashTable object
  • forEach() - Call a function one time for each object
  • initializeIterator() - Prepare to successively visit each object
  • initializeOrderedIterator() - Prepare to visit each object in order
  • nextItem() - Return the next object in the sequence
• General functions
  • getErrorCode() - Get error code

Instance a HashTable object initially using the constructor. Once a HashTable is instanced, an approximate number of objects to be stored may be defined using define(). This allocates an internal array for the storage of object pointers. As objects are inserted HashTable module will expand its internal storage as required. The method inquire() returns the number of objects which may be managed by the presently allocated storage.

Each new object is placed in the hashtable using insert(). The total number of objects contained in the hashtable may be found by calling count(). An object with a specified integer key may be retrieved using lookup(). An object with a given key value may be removed with remove(). The method clear() removes all objects from the hashtable. The maximum key used to store any object may be queried using maxKey(). All keys may be queried using allKeys(). In this case the number of keys returned will be equal to the number of keys returned by count().

Each object in the hashtable may be processed with an “iterator” construct. The method forEach() takes a function as its argument and calls that function repeatedly, each time with an object from the hashtable. The pair of methods initializeIterator() and nextItem() are used to visit each key/object pair using a loop. Call the first method before the body of the loop to prepare the HashTable object for the iteration. Within the loop body, call nextItem(). It will return an integer key and an object each time it is called. It will return zero and a NULL pointer when all of the objects have been processed.

Class Members Descriptions

The currently available HashTable functions are described in detail in this section.

template<typename T>
class HashTable

HashTable class for creating and managing associative containers.

Public Functions

ErrorCode getErrorCode()

Return the current ErrorCode of the HashTable object.

Returns: ErrorCode - The current error code, or NONE if no error.

Status define(int capacity)

Define initial length of storage array. Suggest a number of elements to be stored in the HashTable. This is used to allocate the initial array of storage which is used to hold each integer/object pair. If the number of inserted elements is eventually greater than this initial estimate, storage space will dynamically expanded to hold the extra objects. This function removes any previously entered objects.

See Also inquire() .

Errors

MEMORY is generated if new storage was unable to be allocated.

Parameters:capacity – Estimated number of objects to be held Returns:Status

Status count(int *itemCount)

Get number of contained objects.

Parameters:itemCount – [out] Number of objects held the in HashTable object Returns:Status

Status inquire(int *capacity)

Find the number of objects which may be managed with the presently allocated storage.

See Also define()

Parameters:capacity – Number of objects potentially held Returns:Status

Status insert(int key, T *item)

Place an object in the hashtable. Place the object item in the HashTable object. Associate the integer key with this new object, and remove any object which may have been previously associated with this same key.

Errors

MEMORY is generated if new storage was unable to be allocated.

Parameters:

• key – Integer key value
• item – Pointer to the object

Returns:

Status

Status lookup(int key, Pointer<T> &item)

Find the object at a specified location. Get a pointer to the object associated the specified key. Returns a NULL pointer if no object has been entered with this key, or if the previously inserted object with this key has since been removed.

Parameters:

• key – Integer key of the desired object
• item – [out] Object associated with key

Returns:

Status

Status maxKey(int *maxKey)

Get maximum key value. Get the maximum key value used to store current objects in HashTable.

Parameters:maxKey – [out] Maximum key value Returns:Status

Status remove(int key)

Remove an object from the hashtable. Remove any object associated with the specified key. If no such object is found, then no action is performed.

See Also clear() .

Parameters:key – Key of object to be removed Returns:Status

Status clear()

Remove all objects from the hashtable.

See Also remove() .

Returns:Status

Status allKeys(int keys[])

Get all key values. Get all key values used to store current objects in HashTable. The number of key values returned will be equal the the number of keys returned by the function count() .

Parameters:keys – [out] Array of all keys Returns:Status

Status initializeIterator()

Sequential access to each item.

See Also forEach() .

Returns:Status

Status initializeOrderedIterator()

Initialize iterator for sequential access to each item in arbitrary.

See Also forEach() .

Returns:Status

Status nextItem(int *key, Pointer<T> &item)

Initialize iterator for sequential access to each item in numerical order.

See Also forEach() .

Returns:Status

Status forEach(UnaryFunction *func)

Process each item in the hashtable Calls the supplied function repeatedly, each time using an object from the hashtable as the sole argument to this function. This is useful for releasing a collection of objects before the class destructor is called. The objects are visited in an unspecified order.

Sequential access to each item in the hashtable may also be implemented using initializeIterator() .

Sequential access to each item in numerical order of the hashtable key using initializeOrderedIterator() .

This is followed by repeated calls to the method nextItem() . Each call of the method nextItem() will return a new item from the hashtable, together with its associated key. After every object has been visited in this manner, nextItem() will return a key of zero and a NULL pointer. If the iteration is started using initializeIterator() these pairs (key,item) are visited in arbitrary order. If the iteration is started using initializeOrderedIterator() these pairs (key,item) are visited in numerical order of the key.

Parameters:func – Pointer to function which is to be applied to each object Returns:Status