#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "slist.h"

Typedefs
typedef struct CHtbl_ *	CHtbl

Functions
CHtbl	CHTBLinit (int buckets, int(h)(const void key), int(match)(const void key1, const void key2), void(destroy)(void *data))

void	CHTBLdestroy (CHtbl htbl)

int	CHTBLinsert (CHtbl htbl, const void *data)

int	CHTBLremove (CHtbl htbl, void **data)

int	CHTBLlookup (const CHtbl htbl, void **data)

int	CHTBLsize (CHtbl htbl)

void	CHTBLprint (CHtbl htbl, void(callback)(const void data))

Typedef Documentation

typedef struct CHtbl_* CHtbl

Use a typedef - to hide the interior of CHtbl_ - in the implementation file. This is how data hiding can be done in C.

Definition at line 47 of file chashtbl.h.

Function Documentation

void CHTBLdestroy ( CHtbl htbl )

Destroy the hash table

The table is destroyed - that is, all memory occupied by the elements - will be deallocated. The user-defined callback function destroy, given as an argument to CHTBLinit(), is responsible for freeing dynamically allocated element data, when this function is called. If destroy is set to NULL when CHTBLinit() is called, all data will be left untouched after the table is dismounted and destroyed. When all elements and data have been deallocated - the rest of the table is freed, too.

Parameters

[in] htbl - a reference to current table.

Returns: Nothing.

See Also: CHTBLinit()

Definition at line 77 of file chashtbl.c.

CHtbl CHTBLinit	(	int	buckets,
		int()(const void key)	h,
		int()(const void key1, const void *key2)	match,
		void()(void data)	destroy
	)

Initiate the hash table

Parameters

[in]	buckets	- The number of buckets you want the table to contain when created.
[in]	h	- A reference to a user-defined hash function. This function returns the hash value of the key parameter - given to function h() - when called.
[in]	match	- A reference to a user-defined match function. This function shall return 1 - if key1 is equal to key2 - or 0 otherwise.
[in]	destroy	- A reference to a user-defined function, reponsible for freeing element data, when the table is destroyed. If destroy is set to NULL - then element data will be left untouched upon table destruction.

Returns: A reference - to a new, empty table - if dynamic memory allocation for the ADT was successful - or NULL otherwise. Take really good care of this return value, since it will be needed as a parameter in subsequent calls - to the majority of other table functions in this function interface - i.e. a sort of "handle" to the table.

See Also: CHTBLdestroy()

Definition at line 49 of file chashtbl.c.

int CHTBLinsert	(	CHtbl	htbl,
		const void *	data
	)

Insert data into the hash table

Inserts an element into the current hash table - referenced by the parameter htbl. The data to be inserted, is referenced by parameter data. It is the responsability of the caller to ensure, that this memory is valid as long as it is present in the table.

Parameters

[in]	htbl	- a reference to current table.
[in]	data	- a reference to data to be inserted into the table.

Returns: Value 0 - if insertion was succesful
Value 1 - if the element is already present in the table
Value -1 - otherwise (implies fatal error).

Definition at line 90 of file chashtbl.c.

int CHTBLlookup	(	const CHtbl	htbl,
		void **	data
	)

Lookup data in the table - without removing it

Determines whether an element, with key data matching the data referenced by the parameter data - is present in the current table htbl. This 2nd parameter, data, should reference an (external, user-defined) pointer, that points to the search key data. After the call - this referenced, external pointer has been redirected by this function, to point to the data of the element hit - if the call was succesful. Moreover, a user-defined callback function, responsible for doing the matching of element data - and data referenced by parameter data - must exist for this function to work. This user-supplied match-callback was set when the hash table was initialized - see CHTBLinit().

Parameters

[in]	htbl	- a reference to current table.
[in,out]	data	- a reference to a pointer, pointing at the data to be searched for - at the call. Upon return - this pointer has been redirected by this function - and points instead to data in the element hit - if any.

Returns: Value 0 - if element with matching data was found.
Value -1 - otherwise.

See Also: CHTBLinit()

Definition at line 123 of file chashtbl.c.

void CHTBLprint	(	CHtbl	htbl,
		void()(const void data)	callback
	)

Print all data within the table - on screen

Parameters

[in]	htbl	- reference to current table.
[in]	callback	- reference to user-defined callback function, that gets read access to element data via its parameter data - to do whatever is relevant. In this case it is a matter of formatting data for printing on screen. The printed data should be kept to a minimum (the key value, for example) in order not to clutter the screen. This function is primarily for small tables and debugging purposes.

Returns: - Nothing.

Definition at line 140 of file chashtbl.c.

int CHTBLremove	(	CHtbl	htbl,
		void **	data
	)

Remove an element from the hash table

When called, the 2nd parameter of this function, data, should reference an (external, user-defined) pointer, that points to the search key data. After the call - this referenced, external pointer has been redirected by this function, to point to the data of the removed element - if the call was succesful. The caller is responsible for the future of this memory - deallocating it, if needed, for example. Moreover, a user-defined callback function, responsible for doing the matching of element data - and data referenced by parameter data - must exist for this function to work - otherwise -2 will be returned - always. This user-supplied match-callback was set when the hash table was initialized - see CHTBLinit().

Parameters

[in]	htbl	- reference to current table.
[in,out]	data	- reference to a pointer. After the call, this referenced pointer has been redirected to point to the data of the removed element - if the call was successful. The caller is responsible for the future of this memory - deallocating it, for example.

Returns: Value 0 – if the call was OK - that is, element found and removed.
Value 1 – node not found.
Value -2 – if match-callback is not set.
Value -1 – otherwise (implies fatal error).

Definition at line 109 of file chashtbl.c.

int CHTBLsize ( CHtbl htbl )

Get the number of elements in the table

Parameters

[in] htbl - a reference to the current table.

Returns: The size, that is, the number of elements in the table.

Definition at line 151 of file chashtbl.c.

Typedefs

Functions

Typedef Documentation

Function Documentation