Likewise Base Runtime Library
Hash maps

Key-value hash maps. More...

Data Structures

struct  PLW_HASHMAP_ITER
 Hash map iterator. More...
 
struct  PLW_HASHMAP_PAIR
 Hash pair. More...
 

Macros

#define LW_HASHMAP_ITER_INIT
 Hash map iterator initializer. More...
 

Typedefs

typedef struct _LW_HASHMAP * PLW_HASHMAP
 Hash map structure. More...
 
typedef struct _LW_HASHMAP const * PCLW_HASHMAP
 
typedef LW_VOID(* LW_HASHPAIR_FREE_FUNCTION )(PLW_HASHMAP_PAIR pPair, LW_PVOID pUserData)
 Pair free function. More...
 

Functions

LW_NTSTATUS LwRtlCreateHashMap (LW_OUT PLW_HASHMAP *ppMap, LW_IN LW_HASH_DIGEST_FUNCTION pfnDigest, LW_IN LW_HASH_EQUAL_FUNCTION pfnEqual, LW_IN LW_OPTIONAL LW_PVOID pUserData)
 Create a hash map. More...
 
LW_NTSTATUS LwRtlHashMapInsert (LW_IN LW_OUT PLW_HASHMAP pMap, LW_IN LW_PVOID pKey, LW_IN LW_PVOID pValue, LW_OUT LW_OPTIONAL PLW_HASHMAP_PAIR pPrevPair)
 Insert pair into map. More...
 
LW_NTSTATUS LwRtlHashMapRemove (LW_IN LW_OUT PLW_HASHMAP pMap, LW_IN LW_PCVOID pKey, LW_OUT LW_OPTIONAL PLW_HASHMAP_PAIR pPair)
 Remove pair from map. More...
 
LW_NTSTATUS LwRtlHashMapFindKey (LW_IN PCLW_HASHMAP pMap, LW_OUT LW_OPTIONAL LW_PVOID *ppValue, LW_IN LW_PCVOID pKey)
 Find value by key. More...
 
VOID LwRtlHashMapResetIter (LW_OUT PLW_HASHMAP_ITER pIter)
 Reset hash map iterator. More...
 
BOOLEAN LwRtlHashMapIterate (LW_IN PCLW_HASHMAP pMap, LW_IN LW_OUT PLW_HASHMAP_ITER pIter, LW_OUT PLW_HASHMAP_PAIR pPair)
 Iterate over key-value pairs. More...
 
VOID LwRtlHashMapClear (LW_IN LW_OUT PLW_HASHMAP pMap, LW_IN LW_OPTIONAL LW_HASHPAIR_FREE_FUNCTION pFree, LW_IN LW_OPTIONAL LW_PVOID pUserData)
 Clear hash map. More...
 
ULONG LwRtlHashMapGetCount (LW_IN PCLW_HASHMAP pMap)
 Query hash table pair count. More...
 
VOID LwRtlFreeHashMap (LW_IN LW_OUT PLW_HASHMAP *ppMap)
 Free hash map. More...
 

Detailed Description

The RTL hash map API provides an associative array of key-value pairs backed by a hash table. Unlike the lower-level hash table API, insertions are not guaranteed to succeed.

Macro Definition Documentation

#define LW_HASHMAP_ITER_INIT

A suitable value for statically initializing LW_HASHMAP_ITER structures

Typedef Documentation

typedef struct _LW_HASHMAP* PLW_HASHMAP

An opaque hash map structure

typedef LW_VOID(* LW_HASHPAIR_FREE_FUNCTION)(PLW_HASHMAP_PAIR pPair, LW_PVOID pUserData)

A callback function used by LwRtlHashMapClear() to optionally free any key-value pairs cleared from the table.

Parameters
[in]pPairthe pair to free
[in]pUserDataarbitrary user data

Function Documentation

LW_NTSTATUS LwRtlCreateHashMap ( LW_OUT PLW_HASHMAP ppMap,
LW_IN LW_HASH_DIGEST_FUNCTION  pfnDigest,
LW_IN LW_HASH_EQUAL_FUNCTION  pfnEqual,
LW_IN LW_OPTIONAL LW_PVOID  pUserData 
)

Creates a new hash map with the specified callback functions.

Parameters
[out]ppMapthe created map
[in]pfnDigestthe key digest function
[in]pfnEqualthe key equality function
[in]pUserDataarbitrary user data to pass to callback functions
Return values
LW_STATUS_SUCCESSsuccess
LW_STATUS_INSUFFICIENT_RESOURCESout of memory
LW_NTSTATUS LwRtlHashMapInsert ( LW_IN LW_OUT PLW_HASHMAP  pMap,
LW_IN LW_PVOID  pKey,
LW_IN LW_PVOID  pValue,
LW_OUT LW_OPTIONAL PLW_HASHMAP_PAIR  pPrevPair 
)

Inserts a key-value pair into the hash map, potentially replacing an existing pair with the same key.

Parameters
[in,out]pMapthe hash map
[in]pKeythe key to insert
[in]pValuethe value to insert
[out]pPrevPairif provided, filled in with the previous pair which was kicked out of the table, or NULL if no such pair existed
Return values
LW_STATUS_SUCCESSsuccess
LW_STATUS_INSUFFICIENT_RESOURCESout of memory
LW_NTSTATUS LwRtlHashMapRemove ( LW_IN LW_OUT PLW_HASHMAP  pMap,
LW_IN LW_PCVOID  pKey,
LW_OUT LW_OPTIONAL PLW_HASHMAP_PAIR  pPair 
)

Removes the key-value pair with the specified key from the map.

Parameters
[in,out]pMapthe hash map
[in]pKeythe key to remove
[out]pPairfilled in with the removed pair if provided
Return values
LW_STATUS_SUCCESSsuccess
LW_STATUS_NOT_FOUNDthe specified key was not present in the map
LW_NTSTATUS LwRtlHashMapFindKey ( LW_IN PCLW_HASHMAP  pMap,
LW_OUT LW_OPTIONAL LW_PVOID *  ppValue,
LW_IN LW_PCVOID  pKey 
)

Finds a value in a hash map by the specified key.

Parameters
[in]pMapthe hash map
[out]ppValueset to the value which was found, or NULL on failure
[in]pKeythe key to search for
Return values
LW_STATUS_SUCCESSthe node was found
LW_STATUS_NOT_FOUNDno node with the specified key was found
VOID LwRtlHashMapResetIter ( LW_OUT PLW_HASHMAP_ITER  pIter)

Resets the specified hash map iterator to the start of the map.

Parameters
[out]pIterthe iterator to reset
BOOLEAN LwRtlHashMapIterate ( LW_IN PCLW_HASHMAP  pMap,
LW_IN LW_OUT PLW_HASHMAP_ITER  pIter,
LW_OUT PLW_HASHMAP_PAIR  pPair 
)

Fetches the next key-value pair in the map, returning FALSE if the end of the map has been reached for the given iterator.

Warning
This function has undefined behavior if the map is modified in any way during iteration, with the following exception: a pair just returned by this function may be safely removed with LwRtlHashMapRemove() as long as no other iterator is in active use for the given hash map.
Parameters
[in]pMapthe hash map
[in,out]pIteran iterator which tracks the current position in the map
[out]pPairthe next pair
Return values
TRUEanother pair was placed in pPair
FALSEthe end of the map was reached
VOID LwRtlHashMapClear ( LW_IN LW_OUT PLW_HASHMAP  pMap,
LW_IN LW_OPTIONAL LW_HASHPAIR_FREE_FUNCTION  pFree,
LW_IN LW_OPTIONAL LW_PVOID  pUserData 
)

Removes all nodes from the given hash table. If provided, a free function is called on each removed node.

Parameters
[in,out]pMapthe hash map
[in]pFreean optional callback to invoke on each removed node
[in]pUserDataarbitrary user data to pass to pFree
ULONG LwRtlHashMapGetCount ( LW_IN PCLW_HASHMAP  pMap)

Returns the current count of pairs in the the given hash map.

Parameters
[in]pMapthe hash map
Returns
the current number of nodes in the table
VOID LwRtlFreeHashMap ( LW_IN LW_OUT PLW_HASHMAP ppMap)

Frees the given hash map and sets the pointer to NULL. If *ppTable is already NULL, no action is taken.

Parameters
[in,out]ppMaphash map pointer to free and set to NULL