Key-value hash maps.
More...
|
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...
|
|
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.
#define LW_HASHMAP_ITER_INIT |
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] | pPair | the pair to free |
[in] | pUserData | arbitrary user data |
Creates a new hash map with the specified callback functions.
- Parameters
-
[out] | ppMap | the created map |
[in] | pfnDigest | the key digest function |
[in] | pfnEqual | the key equality function |
[in] | pUserData | arbitrary user data to pass to callback functions |
- Return values
-
LW_STATUS_SUCCESS | success |
LW_STATUS_INSUFFICIENT_RESOURCES | out 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] | pMap | the hash map |
[in] | pKey | the key to insert |
[in] | pValue | the value to insert |
[out] | pPrevPair | if 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_SUCCESS | success |
LW_STATUS_INSUFFICIENT_RESOURCES | out 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] | pMap | the hash map |
[in] | pKey | the key to remove |
[out] | pPair | filled in with the removed pair if provided |
- Return values
-
LW_STATUS_SUCCESS | success |
LW_STATUS_NOT_FOUND | the 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] | pMap | the hash map |
[out] | ppValue | set to the value which was found, or NULL on failure |
[in] | pKey | the key to search for |
- Return values
-
LW_STATUS_SUCCESS | the node was found |
LW_STATUS_NOT_FOUND | no 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] | pIter | the 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] | pMap | the hash map |
[in,out] | pIter | an iterator which tracks the current position in the map |
[out] | pPair | the next pair |
- Return values
-
TRUE | another pair was placed in pPair |
FALSE | the end of the map was reached |
Removes all nodes from the given hash table. If provided, a free function is called on each removed node.
- Parameters
-
[in,out] | pMap | the hash map |
[in] | pFree | an optional callback to invoke on each removed node |
[in] | pUserData | arbitrary 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
-
- 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] | ppMap | hash map pointer to free and set to NULL |