Files
file	AlcHashTable.c
	A general purpose hash table.

Data Structures
struct	_AlcHashItem
	A hash table item. Typedef: AlcHashItem. More...

struct	_AlcHashTable
	A hash table. Typedef: AlcHashTable. More...

Functions
AlcHashTable *	AlcHashTableNew (size_t tableSz, int(keyCmp)(void , void ), unsigned(hashFn)(void ), AlcErrno dstErr)
	Creates a hash table data structure which is required by all the other AlcHashTable functions. More...

AlcHashItem *	AlcHashItemNew (void entry, void(freeFn)(void ), void key, AlcErrno *dstErr)
	Creates a hash item data structure for building into an AlcHashTable. More...

AlcErrno	AlcHashTableFree (AlcHashTable *hTbl)
	Free's the given hash table data structure and any hash table items. More...

AlcErrno	AlcHashTableEntryInsert (AlcHashTable hTbl, void key, void entry, void(freeFn)(void *))
	Inserts the given entry into the hash table. More...

AlcErrno	AlcHashItemUnlink (AlcHashTable hTbl, AlcHashItem rItem, int freeItem)
	Removes the item from the hash table, but does not free the item unless the freeItem flag is set. More...

AlcErrno	AlcHashItemInsert (AlcHashTable hTbl, AlcHashItem newItem)
	Inserts a new item into the hash table. First find the table list head by generating an index from the key using the hash function, then insert the entry into the sorted list. More...

AlcErrno	AlcHashItemFree (AlcHashItem *item)
	Free's the list item which has already been removed from the list. More...

size_t	AlcHashTableCount (AlcHashTable hTbl, AlcErrno dstErr)
	Returns the number of items in the list. More...

AlcHashItem *	AlcHashTableIterate (AlcHashTable hTbl, AlcDirection dir, int(iterFn)(AlcHashTable , AlcHashItem , void ), void iterData, AlcErrno *dstErr)
	Iterates the given function through all entries of the hash table, starting with either the first or last item. The iteration proceeds towards either the last or first item in the table. The iterated function must take the form. More...

AlcErrno	AlcHashTableUnlinkAll (AlcHashTable hTbl, int(testFn)(AlcHashTable , AlcHashItem , void ), void fnData, int freeItems)
	Unlinks all items which are matched by the given match function. If the match pointer function is NULL then all the items are unlinked. The test function should return non-zero to unlink the item passed to it. More...

AlcHashItem *	AlcHashItemGet (AlcHashTable hTbl, void key, AlcErrno *dstErr)
	Gets the item from the hash table with the matching key, it's not an error if a matching item isn't found. More...

int	AlcHashItemOrder (AlcHashTable hTbl, AlcHashItem item0, AlcHashItem *item1)
	Finds the order in which the given items would occur in the hash table. More...

Detailed Description

Function Documentation

AlcHashTable* AlcHashTableNew	(	size_t	tableSz,
		int()(void , void *)	keyCmp,
		unsigned()(void )	hashFn,
		AlcErrno *	dstErr
	)

Creates a hash table data structure which is required by all the other AlcHashTable functions.

Returns: Hash table structure, or NULL on error.

Parameters

tableSz	Hash table size.
keyCmp	Key comparison function.
hashFn	Hash function for table.
dstErr	Destination pointer for error code, may be NULL.

References ALC_ER_ALLOC, ALC_ER_NONE, AlcCalloc(), AlcFree(), _AlcHashTable::hashFn, _AlcHashTable::keyCmp, _AlcHashTable::table, and _AlcHashTable::tableSz.

Referenced by WlzLBTBalanceDomain2D(), and WlzLBTBalanceDomain3D().

AlcHashItem* AlcHashItemNew	(	void *	entry,
		void()(void )	freeFn,
		void *	key,
		AlcErrno *	dstErr
	)

Creates a hash item data structure for building into an AlcHashTable.

Returns: Hash item structure, or NULL on error.

Parameters

entry	New table entry.
freeFn	Function that will be called (if not NULL) to free the entry.
key	Hash key.
dstErr	Destination pointer for error code, may be NULL.

References ALC_ER_ALLOC, ALC_ER_NONE, AlcCalloc(), _AlcHashItem::entry, _AlcHashItem::freeFn, and _AlcHashItem::key.

Referenced by AlcHashTableEntryInsert().

AlcErrno AlcHashTableFree ( AlcHashTable * hTbl )

Free's the given hash table data structure and any hash table items.

Returns: Error code.

Parameters

hTbl	The hash table data structure.

References ALC_ER_NONE, ALC_ER_NULLPTR, AlcFree(), _AlcHashItem::entry, _AlcHashItem::freeFn, _AlcHashItem::next, _AlcHashTable::table, and _AlcHashTable::tableSz.

Referenced by WlzLBTBalanceDomain2D(), and WlzLBTBalanceDomain3D().

AlcErrno AlcHashTableEntryInsert	(	AlcHashTable *	hTbl,
		void *	key,
		void *	entry,
		void()(void )	freeFn
	)

Inserts the given entry into the hash table.

Returns: Error code.

Parameters

hTbl	The hash table data structure.
key	Hash key.
entry	New list entry.
freeFn	Function that will be called (if not NULL) to free the entry should the item be deleted.

References ALC_ER_NONE, ALC_ER_NULLPTR, AlcHashItemFree(), AlcHashItemInsert(), AlcHashItemNew(), and _AlcHashTable::hashFn.

Referenced by WlzLBTClassifyNodeFace3D().

AlcErrno AlcHashItemUnlink	(	AlcHashTable *	hTbl,
		AlcHashItem *	rItem,
		int	freeItem
	)

Removes the item from the hash table, but does not free the item unless the freeItem flag is set.

Returns: Error code.

Parameters

hTbl	The hash table data structure.
rItem	Item to be removed.
freeItem	Free item if non-zero.

References ALC_ER_NONE, ALC_ER_NULLPTR, AlcHashItemFree(), _AlcHashTable::hashFn, _AlcHashItem::key, _AlcHashItem::next, _AlcHashItem::prev, _AlcHashTable::table, and _AlcHashTable::tableSz.

Referenced by AlcHashTableUnlinkAll(), and WlzLBTClassifyNodeFace3D().

AlcErrno AlcHashItemInsert	(	AlcHashTable *	hTbl,
		AlcHashItem *	newItem
	)

Inserts a new item into the hash table. First find the table list head by generating an index from the key using the hash function, then insert the entry into the sorted list.

Returns: Error code.

Parameters

hTbl	The hash table data structure.
newItem	New item to insert.

References ALC_ER_NONE, ALC_ER_NULLPTR, AlcHashItemFree(), _AlcHashTable::hashFn, _AlcHashItem::key, _AlcHashTable::keyCmp, _AlcHashItem::next, _AlcHashItem::prev, _AlcHashTable::table, and _AlcHashTable::tableSz.

Referenced by AlcHashTableEntryInsert().

AlcErrno AlcHashItemFree ( AlcHashItem * item )

Free's the list item which has already been removed from the list.

Returns: Error code.

Parameters

item	Item to be deleted.

References ALC_ER_NONE, ALC_ER_NULLPTR, AlcFree(), _AlcHashItem::entry, and _AlcHashItem::freeFn.

Referenced by AlcHashItemInsert(), AlcHashItemUnlink(), and AlcHashTableEntryInsert().

size_t AlcHashTableCount	(	AlcHashTable *	hTbl,
		AlcErrno *	dstErr
	)

Returns the number of items in the list.

Returns: Number of items in list. This is always >= 0.

Parameters

hTbl	The hash table data structure.
dstErr	Destination pointer for error code, may be NULL.

References ALC_ER_NONE, ALC_ER_NULLPTR, _AlcHashItem::next, _AlcHashTable::table, and _AlcHashTable::tableSz.

AlcHashItem* AlcHashTableIterate	(	AlcHashTable *	hTbl,
		AlcDirection	dir,
		int()(AlcHashTable , AlcHashItem , void )	iterFn,
		void *	iterData,
		AlcErrno *	dstErr
	)

Iterates the given function through all entries of the hash table, starting with either the first or last item. The iteration proceeds towards either the last or first item in the table. The iterated function must take the form.

Returns: Last item.

*                 int MyItemCount(AlcHashTable *hTbl,
*                                 ALC_DIRECTION_FWD,
*                                 void *myData)
*                 {
*                   int         *count;
*
*                   if(hTbl && item)
*                   {
*                     if(keepGoing)
*                     {
*                       count = (int *)myData;
*                       ++*count;
*                     }
*                   }
*                   return(1);
*                 }
*

Where the data parameter is the data supplied to this (AlcHashTableIterate) function. The iteration continues until either the iterated function returns zero or the last/first item of the hash table has been processed.

Parameters

hTbl	The hash table data structure.
dir	Iteration direction.
iterFn	Function to be iterated, see example above.
iterData	Data supplied to the iterated function.
dstErr	Destination pointer for error code, may be NULL.

References ALC_DIRECTION_FWD, ALC_DIRECTION_REV, ALC_ER_NONE, ALC_ER_NULLPTR, ALC_ER_PARAM, _AlcHashItem::next, _AlcHashItem::prev, _AlcHashTable::table, and _AlcHashTable::tableSz.

AlcErrno AlcHashTableUnlinkAll	(	AlcHashTable *	hTbl,
		int()(AlcHashTable , AlcHashItem , void )	testFn,
		void *	fnData,
		int	freeItems
	)

Unlinks all items which are matched by the given match function. If the match pointer function is NULL then all the items are unlinked. The test function should return non-zero to unlink the item passed to it.

Returns: Error code.

Parameters

hTbl	The hash table data structure.
testFn	Function to test items.
fnData	Data supplied to the test function.
freeItems	Free unlinked items if non-zero.

References ALC_ER_NONE, ALC_ER_NULLPTR, AlcHashItemUnlink(), _AlcHashItem::next, and _AlcHashTable::table.

AlcHashItem* AlcHashItemGet	(	AlcHashTable *	hTbl,
		void *	key,
		AlcErrno *	dstErr
	)

Gets the item from the hash table with the matching key, it's not an error if a matching item isn't found.

Returns: Matched item, NULL if no match.

Parameters

hTbl	The hash table data structure.
key	Given key to match.
dstErr	Destination pointer for error code, may be NULL.

References ALC_ER_NONE, ALC_ER_NULLPTR, _AlcHashTable::hashFn, _AlcHashItem::key, _AlcHashTable::keyCmp, _AlcHashItem::next, _AlcHashTable::table, and _AlcHashTable::tableSz.

Referenced by WlzLBTClassifyNodeFace3D().

int AlcHashItemOrder	(	AlcHashTable *	hTbl,
		AlcHashItem *	item0,
		AlcHashItem *	item1
	)

Finds the order in which the given items would occur in the hash table.

Returns: >0 if item0 before item1 or == 0 if item0 is item1 or < 0 if item0 after item1.

Parameters

hTbl	The hash table.
item0	Given item0.
item1	Given item1.

References _AlcHashTable::hashFn, _AlcHashItem::key, _AlcHashItem::next, and _AlcHashTable::tableSz.

Files

Data Structures

Functions

Detailed Description

Function Documentation