Functions



DSHashTable


public:

DSHashTable (     unsigned int newBuckets=100,     unsigned int newPrimeA=89258459,     unsigned int newPrimeB=252584539 );
Discussion

Create a HashTable.

Parameter Descriptions
newBuckets
Specify the number of buckets to be used in the HashTable. The more buckets, the more memory is required; but the faster data access will be on large datasets. You may wish to increase the default for areas involving large quantities of data.
newPrimeA
Specify a large prime number to be used in hashing. You only need to do this if it's important to you to have a different hashing algorithm between two HashTables.
newPrimeB
Specify a large prime number to be used in hashing. You only need to do this if it's important to you to have a different hashing algorithm between two HashTables.

close


public:

void close (void);
Discussion

Purges all data from the HashTable. Leaves the HashTable intact for subsequent use if desired.


delItem


public:

void delItem (     unsigned int Key );
Discussion

Removes one or more entries from the HashTable that have the specified numeric key.

Parameter Descriptions
Key
A numeric key corresponding to the item(s) to be removed from the HashTable.

delItem


public:

void delItem (     const char* Key );
Discussion

Removes one or more entries from the HashTable that have the specified string key.

Parameter Descriptions
Key
A string key corresponding to the item(s) to be removed from the HashTable.

forEach


public:

void forEach (     void (*callback ) (     char *,     char *,     void *),     void * extra );
Discussion

Iterates through the HashTable calling a function for each entry found. This can be useful for doing bulk operations on data in a HashTable; but if you find yourself calling this frequently, consider using a different data structure.

Parameter Descriptions
callback
A function to be called for each entry found in the HashTable. The function will be given a pointer to the key, a pointer to the value, and extra, discussed below.
extra
A pointer to any additional data to be passed to the function for every item encountered. Can be NULL.

getBuckets


public:

unsigned int getBuckets (void);
Discussion

Returns the number of buckets in the HashTable.

function result
The number of buckets in this HashTable.

getElement


public:

DSListElement* getElement (     unsigned int Key );
Discussion

Returns an element matching a specified Key, if such an element exists. Note that this returns a pointer to the raw ListElement object, and this can be used to modify details relating to this particular item. For this reason, use with caution.

Parameter Descriptions
Key
A numeric key matching the element requested.
function result
The ListElement requested, or NULL, if the element could not be found.

getElement


public:

DSListElement* getElement (     const char* Key );
Discussion

Returns an element matching a specified Key, if such an element exists. Note that this returns a pointer to the raw ListElement object, and this can be used to modify details relating to this particular item. For this reason, use with caution.

Parameter Descriptions
Key
A string key matching the element requested.
function result
The ListElement requested, or NULL, if the element could not be found.

getList


public:

DSList* getList (void);
Discussion

Returns a list of data corresponding to the data in the entire HashTable, in no particular order.

function result
A list of items in the HashTable. This list is dynamically created, remember to delete it when you're finished.)

getList


public:

DSList* getList (     unsigned int bucket );
Discussion

Returns a list of data at a particular bucket. Please avoid using this function, it exposes the internal workings of the HashTable. If you need bulk access to data, consider using forEach.

Parameter Descriptions
bucket
Specifies the bucket number to be retrieved.
function result
A list of items at this bucket (or NULL, if there are no entries in this bucket.)

getNumericValue


public:

unsigned int getNumericValue (     const char* Key );
Discussion

Returns the data matching a specified Key, if such an element exists.

Parameter Descriptions
Key
A string key matching the element requested.
function result
The element's data, or NULL, if the element could not be found.

getNumericValue


public:

unsigned int getNumericValue (     unsigned int Key );
Discussion

Returns the data matching a specified Key, if such an element exists.

Parameter Descriptions
Key
A numeric key matching the element requested.
function result
The element's data, or NULL, if the element could not be found.

getPtrValue


public:

void* getPtrValue (     const char* Key );
Discussion

Returns the data matching a specified Key, if such an element exists. Note that this returns a pointer to the data, and this can be used to modify details relating to this particular item. For this reason, use with caution.

Parameter Descriptions
Key
A string key matching the element requested.
function result
A pointer to the element's data, or NULL, if the element could not be found.

getPtrValue


public:

void* getPtrValue (     unsigned int Key );
Discussion

Returns the data matching a specified Key, if such an element exists. Note that this returns a pointer to the data, and this can be used to modify details relating to this particular item. For this reason, use with caution.

Parameter Descriptions
Key
A numeric key matching the element requested.
function result
A pointer to the element's data, or NULL, if the element could not be found.

hash


public:

unsigned int hash (     unsigned char * Key );
Discussion

Hashes the key to generate the bucket that the specified Key would be located in, if it were to be entered.

Parameter Descriptions
Key
A string key.
function result
The bucket which the key corresponds to.

hash


public:

unsigned int hash (     unsigned int value );
Discussion

Hashes the key to generate the bucket that the specified Key would be located in, if it were to be entered.

Parameter Descriptions
Key
A numeric key.
function result
The bucket which the key corresponds to.

init


public:

void init (     unsigned int newBuckets=100,     unsigned int newPrimeA=89258459,     unsigned int newPrimeB=252584539 );
Discussion

Create a HashTable. This function is only provided to allow initiation of a HashTable that has been created by malloc. It should not be used in any other way. The use of malloc is strongly discouraged and new should be used instead. This function may be removed at some point in the future.

Parameter Descriptions
newBuckets
Specify the number of buckets to be used in the HashTable. The more buckets, the more memory is required; but the faster data access will be on large datasets. You may wish to increase the default for areas involving large quantities of data.
newPrimeA
Specify a large prime number to be used in hashing. You only need to do this if it's important to you to have a different hashing algorithm between two HashTables.
newPrimeB
Specify a large prime number to be used in hashing. You only need to do this if it's important to you to have a different hashing algorithm between two HashTables.

insert


public:

void insert (     char * Key,     void * value,     int cleanup=0 );
Discussion

Inserts the specified data into the HashTable.

Parameter Descriptions
Key
A string key. Note that this pointer will be inserted into the HashTable. The HashTable will not copy the data associated with it, so unless the data is permanent, you need to allocate your own memory and set the value of cleanup accordingly.
value
A pointer value. Note that this pointer will be inserted into the HashTable. The HashTable will not copy the data associated with it, so unless the data is permanent, you need to allocate your own memory and set the value of cleanup accordingly.
cleanup
A bitwise combination of flags telling the HashTable what memory it should deallocate if the item is removed. The default is to perform no cleanup, and to leave it to the application. The permissable flags are documented in the ListElement class.

insert


public:

void insert (     unsigned int Key,     void * value,     int cleanup=0 );
Discussion

Inserts the specified data into the HashTable.

Parameter Descriptions
Key
A numeric key.
value
A pointer value. Note that this pointer will be inserted into the HashTable. The HashTable will not copy the data associated with it, so unless the data is permanent, you need to allocate your own memory and set the value of cleanup accordingly.
cleanup
A bitwise combination of flags telling the HashTable what memory it should deallocate if the item is removed. The default is to perform no cleanup, and to leave it to the application. The permissable flags are documented in the ListElement class.

insert


public:

void insert (     char * Key,     unsigned int value,     int cleanup=0 );
Discussion

Inserts the specified data into the HashTable.

Parameter Descriptions
Key
A string key. Note that this pointer will be inserted into the HashTable. The HashTable will not copy the data associated with it, so unless the data is permanent, you need to allocate your own memory and set the value of cleanup accordingly.
value
A numeric value.
cleanup
A bitwise combination of flags telling the HashTable what memory it should deallocate if the item is removed. The default is to perform no cleanup, and to leave it to the application. The permissable flags are documented in the ListElement class.

insert


public:

void insert (     unsigned int Key,     unsigned int value,     int cleanup=0 );
Discussion

Inserts the specified data into the HashTable.

Parameter Descriptions
Key
A numeric key.
value
A numeric value.
cleanup
A bitwise combination of flags telling the HashTable what memory it should deallocate if the item is removed. This value is not relevant for this form of insert, and should be set to 0.

occurenceCount


public:

unsigned int occurenceCount (     const char * key );
Discussion

Counts the number of times the specified Key occurs in the HashTable.

Parameter Descriptions
Key
A string Key.
function result
The number of times the specified Key occurs in the HashTable.

print


public:

void print (void);
Discussion

Dumps the contents of the HashTable to stdout for debugging. Should be removed soon.


setValue


public:

BOOL setValue (     const char* Key,     void * data );
Discussion

Attempts to modify the data of an item matching the specified key, if one exists. This will not modify the cleanup flags of the element.

Parameter Descriptions
Key
A string key matching the element requested.
data
A pointer to the data to be used. Note that this pointer is used directly and will be cleaned up in accordance with the cleanup value of the element.
function result
TRUE if the value was successfully updated; FALSE if the operation could not be completed.

setValue


public:

BOOL setValue (     const char* Key,     unsigned int data );
Discussion

Attempts to modify the data of an item matching the specified key, if one exists. This will not modify the cleanup flags of the element.

Parameter Descriptions
Key
A string key matching the element requested.
data
A piece of numeric data to be used.
function result
TRUE if the value was successfully updated; FALSE if the operation could not be completed.

setValue


public:

BOOL setValue (     unsigned int Key,     void * data );
Discussion

Attempts to modify the data of an item matching the specified key, if one exists. This will not modify the cleanup flags of the element.

Parameter Descriptions
Key
A numeric key matching the element requested.
data
A pointer to the data to be used. Note that this pointer is used directly and will be cleaned up in accordance with the cleanup value of the element.
function result
TRUE if the value was successfully updated; FALSE if the operation could not be completed.

setValue


public:

BOOL setValue (     unsigned int Key,     unsigned int data );
Discussion

Attempts to modify the data of an item matching the specified key, if one exists. This will not modify the cleanup flags of the element.

Parameter Descriptions
Key
A numeric key matching the element requested.
data
A piece of numeric data to be used.
function result
TRUE if the value was successfully updated; FALSE if the operation could not be completed.

~DSHashTable


public:

~DSHashTable (void);
Discussion

Destroy a HashTable.

(Last Updated 9/24/2004)