Woolz Image Processing Version 1.4.0
AlcHashTable

Data Structures

struct  _AlcHashItem
 A hash table item. Typedef: AlcHashItem. More...
struct  _AlcHashTable
 A hash table. Typedef: AlcHashTable. More...

Files

file  AlcHashTable.c
 

A general purpose hash table.


Functions

AlcHashTableAlcHashTableNew (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.
AlcHashItemAlcHashItemNew (void *entry, void(*freeFn)(void *), void *key, AlcErrno *dstErr)
 Creates a hash item data structure for building into an AlcHashTable.
AlcErrno AlcHashTableFree (AlcHashTable *hTbl)
 Free's the given hash table data structure and any hash table items.
AlcErrno AlcHashTableEntryInsert (AlcHashTable *hTbl, void *key, void *entry, void(*freeFn)(void *))
 Inserts the given entry into the hash table.
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.
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.
AlcErrno AlcHashItemFree (AlcHashItem *item)
 Free's the list item which has already been removed from the list.
size_t AlcHashTableCount (AlcHashTable *hTbl, AlcErrno *dstErr)
 Returns the number of items in the list.
AlcHashItemAlcHashTableIterate (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.
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.
AlcHashItemAlcHashItemGet (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.
int AlcHashItemOrder (AlcHashTable *hTbl, AlcHashItem *item0, AlcHashItem *item1)
 Finds the order in which the given items would occur in the hash table.

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:
tableSzHash table size.
keyCmpKey comparison function.
hashFnHash function for table.
dstErrDestination 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:
entryNew table entry.
freeFnFunction that will be called (if not NULL) to free the entry.
keyHash key.
dstErrDestination 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:
hTblThe 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:
hTblThe hash table data structure.
keyHash key.
entryNew list entry.
freeFnFunction 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.

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:
hTblThe hash table data structure.
rItemItem to be removed.
freeItemFree 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().

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:
hTblThe hash table data structure.
newItemNew 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:
itemItem 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:
hTblThe hash table data structure.
dstErrDestination 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:
hTblThe hash table data structure.
dirIteration direction.
iterFnFunction to be iterated, see example above.
iterDataData supplied to the iterated function.
dstErrDestination 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:
hTblThe hash table data structure.
testFnFunction to test items.
fnDataData supplied to the test function.
freeItemsFree 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:
hTblThe hash table data structure.
keyGiven key to match.
dstErrDestination 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.

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:
hTblThe hash table.
item0Given item0.
item1Given item1.

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