Go to the source code of this file.
Typedefs | |
typedef struct le_hashmap * | le_hashmap_Ref_t |
typedef struct le_hashmap_It * | le_hashmap_It_Ref_t |
typedef size_t(* | le_hashmap_HashFunc_t) (const void *keyToHashPtr) |
typedef bool(* | le_hashmap_EqualsFunc_t) (const void *firstKeyPtr, const void *secondKeyPtr) |
typedef bool(* | le_hashmap_ForEachHandler_t) (const void *keyPtr, const void *valuePtr, void *contextPtr) |
Detailed Description
Legato HashMap API include file.
Copyright (C) Sierra Wireless Inc.
Typedef Documentation
typedef bool(* le_hashmap_EqualsFunc_t) (const void *firstKeyPtr, const void *secondKeyPtr) |
Prototype for equality functions. The equality function returns true if the the keys point to values are equivalent. The HashMap doesn't know in advance which types are to be stored so this function must be supplied by the caller.
- Parameters
-
firstKeyPtr Pointer to the first key for comparing. secondKeyPtr Pointer to the second key for comparing.
- Returns
- Returns true if the values are the same, false otherwise
typedef bool(* le_hashmap_ForEachHandler_t) (const void *keyPtr, const void *valuePtr, void *contextPtr) |
Prototype for callback functions for the iterator function le_hashmap_ForEach(). This function should return true in order to continue iterating, or false to stop.
- Parameters
-
keyPtr Pointer to the key at the current position in the map valuePtr Pointer to the value associated to this key contextPtr Pointer to the context supplied to le_hashmap_ForEach()
- Returns
- Returns true to continue, false to stop
typedef size_t(* le_hashmap_HashFunc_t) (const void *keyToHashPtr) |
Prototype for hash functions. The hash function must generate a good spread of hashes without consuming lots of processing power.
- Parameters
-
keyToHashPtr Pointer to the key which will be hashed
- Returns
- The calculated hash value
typedef struct le_hashmap_It* le_hashmap_It_Ref_t |
Reference to a HashMap Iterator.
typedef struct le_hashmap* le_hashmap_Ref_t |
Reference to a HashMap.
Function Documentation
bool le_hashmap_ContainsKey | ( | le_hashmap_Ref_t | mapRef, |
const void * | keyPtr | ||
) |
Tests if the HashMap contains a particular key.
- Returns
- Returns true if the key is found, false otherwise.
- Parameters
-
[in] mapRef Reference to the map. [in] keyPtr Pointer to the key to be searched.
size_t le_hashmap_CountCollisions | ( | le_hashmap_Ref_t | mapRef | ) |
Counts the total number of collisions in the map. A collision occurs when more than one entry is stored in the map at the same index.
- Returns
- Returns the total collisions in the map.
- Parameters
-
[in] mapRef Reference to the map.
le_hashmap_Ref_t le_hashmap_Create | ( | const char * | nameStr, |
size_t | capacity, | ||
le_hashmap_HashFunc_t | hashFunc, | ||
le_hashmap_EqualsFunc_t | equalsFunc | ||
) |
Create a HashMap.
If you create a hashmap with a smaller capacity than you actually use, then the map will continue to work, but performance will degrade the more you put in the map.
- Returns
- Returns a reference to the map.
- Note
- Terminates the process on failure, so no need to check the return value for errors.
- Parameters
-
[in] nameStr Name of the HashMap [in] capacity Size of the hashmap [in] hashFunc Hash function [in] equalsFunc Equality function
void le_hashmap_EnableTrace | ( | le_hashmap_Ref_t | mapRef | ) |
Immediately enables tracing on a particular hashmap object.
- Parameters
-
[in] mapRef Reference to the map.
bool le_hashmap_EqualsString | ( | const void * | firstStringPtr, |
const void * | secondStringPtr | ||
) |
String equality function. Can be used as a parameter to le_hashmap_Create() if the key to the table is a string
- Returns
- Returns true if the strings are identical, false otherwise.
- Parameters
-
[in] firstStringPtr Pointer to the first string for comparing. [in] secondStringPtr Pointer to the second string for comparing.
bool le_hashmap_EqualsUInt32 | ( | const void * | firstIntPtr, |
const void * | secondIntPtr | ||
) |
Integer equality function. Can be used as a parameter to le_hashmap_Create() if the key to the table is a uint32_t.
- Returns
- Returns true if the integers are equal, false otherwise.
- Parameters
-
[in] firstIntPtr Pointer to the first integer for comparing. [in] secondIntPtr Pointer to the second integer for comparing.
bool le_hashmap_EqualsUInt64 | ( | const void * | firstIntPtr, |
const void * | secondIntPtr | ||
) |
Long integer equality function. This can be used as a paramter to le_hashmap_Create if the key to the table is a uint64_t
- Returns
- Returns true if the integers are equal, false otherwise
- Parameters
-
[in] firstIntPtr Pointer to the first long integer for comparing. [in] secondIntPtr Pointer to the second long integer for comparing.
bool le_hashmap_EqualsVoidPointer | ( | const void * | firstVoidPtr, |
const void * | secondVoidPtr | ||
) |
Pointer equality function. Can be used as a parameter to le_hashmap_Create() if the key to the table is an pointer or reference.
- Returns
- Returns true if the pointers are equal, false otherwise
- Parameters
-
[in] firstVoidPtr First pointer for comparing. [in] secondVoidPtr Second pointer for comparing.
void le_hashmap_ForEach | ( | le_hashmap_Ref_t | mapRef, |
le_hashmap_ForEachHandler_t | forEachFn, | ||
void * | contextPtr | ||
) |
Iterates over the whole map, calling the supplied callback with each key-value pair. If the callback returns false for any key then this function will return.
- Returns
- Returns nothing
- Parameters
-
[in] mapRef Reference to the map. [in] forEachFn Callback function to be called with each pair. [in] contextPtr Pointer to a context to be supplied to the callback.
void* le_hashmap_Get | ( | le_hashmap_Ref_t | mapRef, |
const void * | keyPtr | ||
) |
Retrieve a value from a HashMap.
- Returns
- Returns a pointer to the value or NULL if the key is not found.
- Parameters
-
[in] mapRef Reference to the map. [in] keyPtr Pointer to the key to be retrieved.
le_result_t le_hashmap_GetFirstNode | ( | le_hashmap_Ref_t | mapRef, |
void ** | firstKeyPtr, | ||
void ** | firstValuePtr | ||
) |
Retrieves the key and value of the first node stored in the hashmap. The hashmap is not sorted so this will simply return the first node stored in the map. There is no guarantee that a subsequent call to this function will return the same pair if new keys have been added to the map. If NULL is passed as the firstValuePointer then only the key will be returned.
- Returns
- LE_OK if the first node is returned or LE_NOT_FOUND if the map is empty. LE_BAD_PARAMETER if the key is NULL.
- Parameters
-
[in] mapRef Reference to the map [out] firstKeyPtr Pointer to the first key [out] firstValuePtr Pointer to the first value
le_hashmap_It_Ref_t le_hashmap_GetIterator | ( | le_hashmap_Ref_t | mapRef | ) |
Gets an iterator for step-by-step iteration over the map. In this mode, the iteration is controlled by the calling function using the le_hashmap_NextNode() function. There is one iterator per map, and calling this function resets the iterator position to the start of the map. The iterator is not ready for data access until le_hashmap_NextNode() has been called at least once.
- Returns
- Returns A reference to a hashmap iterator which is ready for le_hashmap_NextNode() to be called on it
- Parameters
-
[in] mapRef Reference to the map.
const void* le_hashmap_GetKey | ( | le_hashmap_It_Ref_t | iteratorRef | ) |
Retrieves a pointer to the key where the iterator is currently pointing. If the iterator has just been initialized and le_hashmap_NextNode() has not been called, or if the iterator has been invalidated, this will return NULL.
- Returns
- Pointer to the current key, or NULL if the iterator has been invalidated or is not ready.
- Parameters
-
[in] iteratorRef Reference to the iterator.
le_result_t le_hashmap_GetNodeAfter | ( | le_hashmap_Ref_t | mapRef, |
const void * | keyPtr, | ||
void ** | nextKeyPtr, | ||
void ** | nextValuePtr | ||
) |
Retrieves the key and value of the node after the passed in key. The hashmap is not sorted so this will simply return the next node stored in the map. There is no guarantee that a subsequent call to this function will return the same pair if new keys have been added to the map. If NULL is passed as the nextValuePtr then only the key will be returned.
- Returns
- LE_OK if the next node is returned. If the keyPtr is not found in the map then LE_BAD_PARAMETER is returned. LE_NOT_FOUND is returned if the passed in key is the last one in the map.
- Parameters
-
[in] mapRef Reference to the map [in] keyPtr Pointer to the key to be searched for [out] nextKeyPtr Pointer to the first key [out] nextValuePtr Pointer to the first value
void* le_hashmap_GetStoredKey | ( | le_hashmap_Ref_t | mapRef, |
const void * | keyPtr | ||
) |
Retrieve a stored key from a HashMap.
- Returns
- Returns a pointer to the key that was stored in the HashMap by le_hashmap_Put() or NULL if the key is not found.
- Parameters
-
[in] mapRef Reference to the map. [in] keyPtr Pointer to the key to be retrieved.
void* le_hashmap_GetValue | ( | le_hashmap_It_Ref_t | iteratorRef | ) |
Retrieves a pointer to the value where the iterator is currently pointing. If the iterator has just been initialized and le_hashmap_NextNode() has not been called, or if the iterator has been invalidated, this will return NULL.
- Returns
- Pointer to the current value, or NULL if the iterator has been invalidated or is not ready.
- Parameters
-
[in] iteratorRef Reference to the iterator.
size_t le_hashmap_HashString | ( | const void * | stringToHashPtr | ) |
String hashing function. Can be used as a parameter to le_hashmap_Create() if the key to the table is a string.
- Returns
- Returns the hash value of the string pointed to by stringToHash.
- Parameters
-
[in] stringToHashPtr Pointer to the string to be hashed.
size_t le_hashmap_HashUInt32 | ( | const void * | intToHashPtr | ) |
Integer hashing function. Can be used as a parameter to le_hashmap_Create() if the key to the table is a uint32_t.
- Returns
- Returns the hash value of the uint32_t pointed to by intToHash.
- Parameters
-
[in] intToHashPtr Pointer to the integer to be hashed.
size_t le_hashmap_HashUInt64 | ( | const void * | intToHashPtr | ) |
Long integer hashing function. This can be used as a paramter to le_hashmap_Create if the key to the table is a uint64_t
- Returns
- Returns the hash value of the uint64_t pointed to by intToHash
- Parameters
-
[in] intToHashPtr Pointer to the long integer to be hashed
size_t le_hashmap_HashVoidPointer | ( | const void * | voidToHashPtr | ) |
Pointer hashing function. Can be used as a parameter to le_hashmap_Create() if the key to the table is an pointer or reference. Simply pass in the address as the key.
- Returns
- Returns the hash value of the pointer pointed to by voidToHashPtr
- Parameters
-
[in] voidToHashPtr Pointer to be hashed
bool le_hashmap_isEmpty | ( | le_hashmap_Ref_t | mapRef | ) |
Tests if the HashMap is empty (i.e. contains zero keys).
- Returns
- Returns true if empty, false otherwise.
- Parameters
-
[in] mapRef Reference to the map.
void le_hashmap_MakeTraceable | ( | le_hashmap_Ref_t | mapRef | ) |
Makes a particular hashmap traceable without enabling the tracing. After this is called, when the trace keyword for this hashmap (the hashmap's name) is enabled for the "framework" component in the process, tracing will start. If that keyword was enabled before this function was called, tracing will start immediately when it is called.
- Parameters
-
[in] mapRef Reference to the map.
le_result_t le_hashmap_NextNode | ( | le_hashmap_It_Ref_t | iteratorRef | ) |
Moves the iterator to the next key/value pair in the map. Order is dependent on the hash algorithm and the order of inserts, and is not sorted at all.
- Returns
- Returns LE_OK unless you go past the end of the map, then returns LE_NOT_FOUND.
- Parameters
-
[in] iteratorRef Reference to the iterator.
le_result_t le_hashmap_PrevNode | ( | le_hashmap_It_Ref_t | iteratorRef | ) |
Moves the iterator to the previous key/value pair in the map. Order is dependent on the hash algorithm and the order of inserts, and is not sorted at all.
- Returns
- Returns LE_OK unless you go past the beginning of the map, then returns LE_NOT_FOUND.
- Parameters
-
[in] iteratorRef Reference to the iterator
void* le_hashmap_Put | ( | le_hashmap_Ref_t | mapRef, |
const void * | keyPtr, | ||
const void * | valuePtr | ||
) |
Add a key-value pair to a HashMap. If the key already exists in the map, the previous value will be replaced with the new value passed into this function.
- Returns
- Returns NULL for a new entry or a pointer to the old value if it is replaced.
- Parameters
-
[in] mapRef Reference to the map. [in] keyPtr Pointer to the key to be stored. [in] valuePtr Pointer to the value to be stored.
void* le_hashmap_Remove | ( | le_hashmap_Ref_t | mapRef, |
const void * | keyPtr | ||
) |
Remove a value from a HashMap.
- Returns
- Returns a pointer to the value or NULL if the key is not found.
- Parameters
-
[in] mapRef Reference to the map. [in] keyPtr Pointer to the key to be removed.
void le_hashmap_RemoveAll | ( | le_hashmap_Ref_t | mapRef | ) |
Deletes all the entries held in the hashmap. This will not delete the data pointed to by the key and value pointers. That cleanup is the responsibility of the caller. This allows the map to be re-used. Currently maps can't be deleted.
- Parameters
-
[in] mapRef Reference to the map.
size_t le_hashmap_Size | ( | le_hashmap_Ref_t | mapRef | ) |
Calculates the number of keys in the HashMap.
- Returns
- The number of keys in the HashMap.
- Parameters
-
[in] mapRef Reference to the map.