rtxHashMap.h File Reference

Generic hash map interface. More...

#include "rtxsrc/rtxContext.h"

Go to the source code of this file.


Classes

struct  HASHMAPENTRYTYPE
struct  HASHMAPTYPENAME

Defines

#define HASHMAPTYPENAME   OSRTHashMap
#define HASHMAPENTRYTYPE   OSRTHashMapEntry
#define HASHMAPKEYTYPE   void*
#define HASHMAPVALUETYPE   void*
#define HASHMAPINITFUNC   rtxHashMapInit
#define HASHMAPNEWFUNC   rtxNewHashMap
#define HASHMAPCOPYFUNC   rtxHashMapCopy
#define HASHMAPFREEFUNC   rtxHashMapFree
#define HASHMAPINSERTFUNC   rtxHashMapInsert
#define HASHMAPPUTFUNC   rtxHashMapPut
#define HASHMAPREMOVEFUNC   rtxHashMapRemove
#define HASHMAPSEARCHFUNC   rtxHashMapSearch
#define HASHMAPSORTFUNC   rtxHashMapSort

Functions

EXTERNRT void HASHMAPINITFUNC (OSCTXT *pctxt, HASHMAPTYPENAME *pHashMap, size_t capacity, OSUINT32(*hashFunc)(HASHMAPKEYTYPE), OSBOOL(*keyEqualsFunc)(HASHMAPKEYTYPE, HASHMAPKEYTYPE))
 This function initializes the hash map.
EXTERNRT HASHMAPTYPENAME * HASHMAPNEWFUNC (OSCTXT *pctxt, size_t capacity, OSUINT32(*hashFunc)(HASHMAPKEYTYPE), OSBOOL(*keyEqualsFunc)(HASHMAPKEYTYPE, HASHMAPKEYTYPE))
 This function creates a new hash map.
EXTERNRT HASHMAPTYPENAME * HASHMAPCOPYFUNC (OSCTXT *pctxt, HASHMAPTYPENAME *pHashMap)
 This function creates a copy of an existing hash map.
EXTERNRT void HASHMAPFREEFUNC (OSCTXT *pctxt, HASHMAPTYPENAME *pHashMap)
 This function frees all entries within an existing hash map.
EXTERNRT int HASHMAPINSERTFUNC (OSCTXT *pctxt, HASHMAPTYPENAME *pHashMap, HASHMAPKEYTYPE key, HASHMAPVALUETYPE value)
 This function inserts an entry into the hash map.
EXTERNRT OSBOOL HASHMAPSEARCHFUNC (HASHMAPTYPENAME *pHashMap, HASHMAPKEYTYPE key, HASHMAPVALUETYPE *pvalue)
 This function searches for an entry in the hash map.
EXTERNRT OSBOOL HASHMAPREMOVEFUNC (OSCTXT *pctxt, HASHMAPTYPENAME *pHashMap, HASHMAPKEYTYPE key, HASHMAPVALUETYPE *pvalue)
 This function removes an entry from the hash map.
EXTERNRT int HASHMAPPUTFUNC (OSCTXT *pctxt, HASHMAPTYPENAME *pHashMap, HASHMAPKEYTYPE key, HASHMAPVALUETYPE value)
 This function inserts/replaces an entry into the hash map.
EXTERNRT int HASHMAPSORTFUNC (OSCTXT *pctxt, HASHMAPTYPENAME *pHashMap, OSRTDList *pSortedList, int(*compareFunc)(HASHMAPKEYTYPE key1, HASHMAPKEYTYPE key2))
 This function sorts the hash map in ascending order using the given key compare function.

Detailed Description

Generic hash map interface.

This relates a generic key structure (void*) to a generic value (void*). Based on "C Hash Table" public domain code.

Definition in file rtxHashMap.h.

Function Documentation

EXTERNRT HASHMAPTYPENAME* HASHMAPCOPYFUNC ( OSCTXT *  pctxt,
HASHMAPTYPENAME *  pHashMap 
)

This function creates a copy of an existing hash map.

Parameters:
pctxt Pointer to a context structure.
pHashMap Pointer to hash map structure to copy.
Returns:
Allocated and copied hash map structure or NULL if insufficient dynamic memory is available to hold the structure.

EXTERNRT void HASHMAPFREEFUNC ( OSCTXT *  pctxt,
HASHMAPTYPENAME *  pHashMap 
)

This function frees all entries within an existing hash map.

It does not free the structure itself.

Parameters:
pctxt Pointer to a context structure.
pHashMap Pointer to hash map structure to free.

EXTERNRT void HASHMAPINITFUNC ( OSCTXT *  pctxt,
HASHMAPTYPENAME *  pHashMap,
size_t  capacity,
OSUINT32(*)(HASHMAPKEYTYPE)  hashFunc,
OSBOOL(*)(HASHMAPKEYTYPE, HASHMAPKEYTYPE)  keyEqualsFunc 
)

This function initializes the hash map.

Parameters:
pctxt Pointer to a context structure.
pHashMap Pointer to hash map structure.
capacity Capacity of the hash map or zero to use default.
hashFunc Hash callback function.
keyEqualsFunc Key equals callback function.

EXTERNRT int HASHMAPINSERTFUNC ( OSCTXT *  pctxt,
HASHMAPTYPENAME *  pHashMap,
HASHMAPKEYTYPE  key,
HASHMAPVALUETYPE  value 
)

This function inserts an entry into the hash map.

The table will be expanded if the insertion would take the ratio of entries to table size over the maximum load factor.

This function does not check for repeated insertions with a duplicate key. The value returned when using a duplicate key is undefined -- when the hashtable changes size, the order of retrieval of duplicate key entries is reversed. If in doubt, remove before insert.

Parameters:
pctxt Pointer to a context structure.
pHashMap Pointer to hash map structure.
key Key value. Memory is owned by caller.
value Value to insert. Memory is owned by caller.
Returns:
Zero if insertion was successful, a negative status code otherwise.

EXTERNRT HASHMAPTYPENAME* HASHMAPNEWFUNC ( OSCTXT *  pctxt,
size_t  capacity,
OSUINT32(*)(HASHMAPKEYTYPE)  hashFunc,
OSBOOL(*)(HASHMAPKEYTYPE, HASHMAPKEYTYPE)  keyEqualsFunc 
)

This function creates a new hash map.

Parameters:
pctxt Pointer to a context structure.
capacity Capacity of the map or zero to use default.
hashFunc Hash callback function.
keyEqualsFunc Key equals callback function.
Returns:
Allocated hash map structure or NULL if insufficient dynamic memory is available to hold the structure.

EXTERNRT int HASHMAPPUTFUNC ( OSCTXT *  pctxt,
HASHMAPTYPENAME *  pHashMap,
HASHMAPKEYTYPE  key,
HASHMAPVALUETYPE  value 
)

This function inserts/replaces an entry into the hash map.

If the key already exists in the map, its value is updated. Otherwise, the key/value pair is inserted.

Parameters:
pctxt Pointer to a context structure.
pHashMap Pointer to hash map structure.
key Key value. Memory is owned by caller.
value Value to insert/replace. Memory is owned by caller.
Returns:
Zero if operation was successful, a negative status code otherwise.

EXTERNRT OSBOOL HASHMAPREMOVEFUNC ( OSCTXT *  pctxt,
HASHMAPTYPENAME *  pHashMap,
HASHMAPKEYTYPE  key,
HASHMAPVALUETYPE *  pvalue 
)

This function removes an entry from the hash map.

Parameters:
pctxt Pointer to a context structure.
pHashMap Pointer to hash map structure.
key Key value. Memory is owned by caller.
pvalue Pointer to value to receive search result value.
Returns:
Boolean result: true if found and removed.

EXTERNRT OSBOOL HASHMAPSEARCHFUNC ( HASHMAPTYPENAME *  pHashMap,
HASHMAPKEYTYPE  key,
HASHMAPVALUETYPE *  pvalue 
)

This function searches for an entry in the hash map.

Parameters:
pHashMap Pointer to hash map structure.
key Key value. Memory is owned by caller.
pvalue Pointer to value to receive search result value.
Returns:
Boolean search result: true if found; false if not.

EXTERNRT int HASHMAPSORTFUNC ( OSCTXT *  pctxt,
HASHMAPTYPENAME *  pHashMap,
OSRTDList *  pSortedList,
int(*)(HASHMAPKEYTYPE key1, HASHMAPKEYTYPE key2)  compareFunc 
)

This function sorts the hash map in ascending order using the given key compare function.

Parameters:
pctxt Pointer to a context structure.
pHashMap Pointer to hash map structure.
compareFunc Comparison function for key values.
pSortedList Pointer to linked list structure to receive sorted values. Entries within the list are items from the hash map themselves, not copies. List memory may be freed by calling rtxDListFreeNodes.
Returns:
Status of operation: 0 = success or negative status code.