ohashtbl.h File Reference

#include <stdio.h>
#include <stdlib.h>

Go to the source code of this file.

Typedefs
typedef struct OHtbl_ *	OHtbl

Functions
OHtbl	OHTBLinit (int positions, int(*h1)(const void *key), int(*h2)(const void *key), int(*match)(const void *key1, const void *key2), void(*destroy)(void *data))
void	OHTBLdestroy (OHtbl htbl)
int	OHTBLinsert (OHtbl htbl, const void *data)
int	OHTBLremove (OHtbl htbl, void **data)
int	OHTBLlookup (const OHtbl htbl, void **data)
int	OHTBLsize (OHtbl htbl)
void	OHTBLprint (OHtbl htbl, void(*callback)(const void *data))

Typedef Documentation

typedef struct OHtbl_* OHtbl

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

Definition at line 38 of file ohashtbl.h.

Function Documentation

void OHTBLdestroy

(

OHtbl

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

OHTBLinit()

Definition at line 81 of file ohashtbl.c.

OHtbl OHTBLinit	(	int	positions,
		int(*)(const void *key)	h1,
		int(*)(const void *key)	h2,
		int(*)(const void *key1, const void *key2)	match,
		void(*)(void *data)	destroy
	)

Initialize the open-addressed hash table

Parameters

[in]	positions	- The number of positions you want the table to contain when created.
[in]	h1	- A reference to a user-defined hash function. This function returns the hash value of the key parameter - given to function h1() - when called.
[in]	h2	- A reference to a user-defined hash function. This function returns the hash value of the key parameter - given to function h2() - 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

OHTBLdestroy()

Definition at line 46 of file ohashtbl.c.

int OHTBLinsert	(	OHtbl	htbl,
		const void *	data
	)

Insert a data element into the 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 102 of file ohashtbl.c.

int OHTBLlookup	(	const OHtbl	htbl,
		void **	data
	)

Determine if a data element exists in the table

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 OHTBLinit().

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

OHTBLinit()

Definition at line 168 of file ohashtbl.c.

void OHTBLprint	(	OHtbl	htbl,
		void(*)(const void *data)	callback
	)

Print all data of the open-addressed hash 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 199 of file ohashtbl.c.

int OHTBLremove	(	OHtbl	htbl,
		void **	data
	)

Remove a data element from the 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. This user-supplied match-callback was set when the hash table was initialized - see OHTBLinit().

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.

Definition at line 135 of file ohashtbl.c.

int OHTBLsize

(

OHtbl

htbl

)

Get the size of 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 194 of file ohashtbl.c.