rtxHashMap.h File Reference

Generic hash map interface. More...

#include "rtxsrc/rtxContext.h"

Go to the source code of this file.

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 (http://www.cl.cam.ac.uk/~cwc22/hashtable/).

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.