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)

Functions
le_hashmap_Ref_t	le_hashmap_Create (const char *nameStr, size_t capacity, le_hashmap_HashFunc_t hashFunc, le_hashmap_EqualsFunc_t equalsFunc)

void *	le_hashmap_Put (le_hashmap_Ref_t mapRef, const void keyPtr, const void valuePtr)

void *	le_hashmap_Get (le_hashmap_Ref_t mapRef, const void *keyPtr)

void *	le_hashmap_GetStoredKey (le_hashmap_Ref_t mapRef, const void *keyPtr)

void *	le_hashmap_Remove (le_hashmap_Ref_t mapRef, const void *keyPtr)

bool	le_hashmap_isEmpty (le_hashmap_Ref_t mapRef)

size_t	le_hashmap_Size (le_hashmap_Ref_t mapRef)

bool	le_hashmap_ContainsKey (le_hashmap_Ref_t mapRef, const void *keyPtr)

void	le_hashmap_RemoveAll (le_hashmap_Ref_t mapRef)

void	le_hashmap_ForEach (le_hashmap_Ref_t mapRef, le_hashmap_ForEachHandler_t forEachFn, void *contextPtr)

le_hashmap_It_Ref_t	le_hashmap_GetIterator (le_hashmap_Ref_t mapRef)

le_result_t	le_hashmap_NextNode (le_hashmap_It_Ref_t iteratorRef)

le_result_t	le_hashmap_PrevNode (le_hashmap_It_Ref_t iteratorRef)

void const *	le_hashmap_GetKey (le_hashmap_It_Ref_t iteratorRef)

void const *	le_hashmap_GetValue (le_hashmap_It_Ref_t iteratorRef)

le_result_t	le_hashmap_GetFirstNode (le_hashmap_Ref_t mapRef, void firstKeyPtr, void firstValuePtr)

le_result_t	le_hashmap_GetNodeAfter (le_hashmap_Ref_t mapRef, const void keyPtr, void nextKeyPtr, void *nextValuePtr)

size_t	le_hashmap_CountCollisions (le_hashmap_Ref_t mapRef)

size_t	le_hashmap_HashString (const void *stringToHashPtr)

bool	le_hashmap_EqualsString (const void firstStringPtr, const void secondStringPtr)

size_t	le_hashmap_HashUInt32 (const void *intToHashPtr)

bool	le_hashmap_EqualsUInt32 (const void firstIntPtr, const void secondIntPtr)

size_t	le_hashmap_HashVoidPointer (const void *voidToHashPtr)

bool	le_hashmap_EqualsVoidPointer (const void firstVoidPtr, const void secondVoidPtr)

void	le_hashmap_MakeTraceable (le_hashmap_Ref_t mapRef)

void	le_hashmap_EnableTrace (le_hashmap_Ref_t mapRef)

Detailed Description

Legato HashMap API include file.

Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.

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_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.

void const* 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 const* 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_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.

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation