rcutils  master
C API providing common utilities and data structures.
Classes | Macros | Typedefs | Functions
hash_map.h File Reference
#include <string.h>
#include "rcutils/allocator.h"
#include "rcutils/types/rcutils_ret.h"
#include "rcutils/macros.h"
#include "rcutils/visibility_control.h"
Include dependency graph for hash_map.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

struct  rcutils_hash_map_t
 The structure holding the metadata for a hash map. More...
 

Macros

#define HASH_MAP_VALIDATE_HASH_MAP(map)
 

Typedefs

typedef struct rcutils_hash_map_t rcutils_hash_map_t
 The structure holding the metadata for a hash map. More...
 
typedef size_t(* rcutils_hash_map_key_hasher_t) (const void *)
 The function signature for a key hashing function. More...
 
typedef int(* rcutils_hash_map_key_cmp_t) (const void *, const void *)
 The function signature for a key comparison function. More...
 

Functions

size_t rcutils_hash_map_string_hash_func (const void *key_str)
 A hashing function for a null terminated c string. More...
 
int rcutils_hash_map_string_cmp_func (const void *val1, const void *val2)
 A comparison function for a null terminated c string. More...
 
rcutils_hash_map_t rcutils_get_zero_initialized_hash_map ()
 Return an empty hash_map struct. More...
 
rcutils_ret_t rcutils_hash_map_init (rcutils_hash_map_t *hash_map, size_t initial_capacity, size_t key_size, size_t data_size, rcutils_hash_map_key_hasher_t key_hashing_func, rcutils_hash_map_key_cmp_t key_cmp_func, const rcutils_allocator_t *allocator)
 Initialize a rcutils_hash_map_t, allocating space for given capacity. More...
 
rcutils_ret_t rcutils_hash_map_fini (rcutils_hash_map_t *hash_map)
 Finalize the previously initialized hash_map struct. More...
 
rcutils_ret_t rcutils_hash_map_get_capacity (const rcutils_hash_map_t *hash_map, size_t *capacity)
 Get the current capacity of the hash_map. More...
 
rcutils_ret_t rcutils_hash_map_get_size (const rcutils_hash_map_t *hash_map, size_t *size)
 Get the current size of the hash_map. More...
 
rcutils_ret_t rcutils_hash_map_set (rcutils_hash_map_t *hash_map, const void *key, const void *value)
 Set a key value pair in the hash_map, increasing capacity if necessary. More...
 
rcutils_ret_t rcutils_hash_map_unset (rcutils_hash_map_t *hash_map, const void *key)
 Unset a key value pair in the hash_map. More...
 
bool rcutils_hash_map_key_exists (const rcutils_hash_map_t *hash_map, const void *key)
 Get whether or not a key exists. More...
 
rcutils_ret_t rcutils_hash_map_get (const rcutils_hash_map_t *hash_map, const void *key, void *data)
 Get value given a key. More...
 
rcutils_ret_t rcutils_hash_map_get_next_key_and_data (const rcutils_hash_map_t *hash_map, const void *previous_key, void *key, void *data)
 Get the next key in the hash_map, unless NULL is given, then get the first key. More...
 

Macro Definition Documentation

◆ HASH_MAP_VALIDATE_HASH_MAP

#define HASH_MAP_VALIDATE_HASH_MAP (   map)
Value:
if (NULL == map->impl) { \
RCUTILS_SET_ERROR_MSG("map is not initialized"); \
}

Validates that an rcutils_hash_map_t* points to a valid hash map.

Parameters
[in]mapA pointer to an rcutils_hash_map_t
Returns
RCUTILS_RET_INVALID_ARGUMENT if map is null
RCUTILS_RET_NOT_INITIALIZED if map is not initialized.

Typedef Documentation

◆ rcutils_hash_map_t

The structure holding the metadata for a hash map.

◆ rcutils_hash_map_key_hasher_t

typedef size_t(* rcutils_hash_map_key_hasher_t) (const void *)

The function signature for a key hashing function.

Parameters
[in]keyThe key that needs to be hashed
Returns
A hash value for the provided string

◆ rcutils_hash_map_key_cmp_t

typedef int(* rcutils_hash_map_key_cmp_t) (const void *, const void *)

The function signature for a key comparison function.

Parameters
[in]val1The first value to compare
[in]val2The second value to compare
Returns
A negative number if val1 < val2, or
A positve number if val1 > val2, or
Zero if val1 == val2.

Function Documentation

◆ rcutils_hash_map_string_hash_func()

size_t rcutils_hash_map_string_hash_func ( const void *  key_str)

A hashing function for a null terminated c string.

A hashing function for a null terminated c string. Should be used when your key is just a pointer to a c-string

◆ rcutils_hash_map_string_cmp_func()

int rcutils_hash_map_string_cmp_func ( const void *  val1,
const void *  val2 
)

A comparison function for a null terminated c string.

A comparison function for a null terminated c string. Should be used when your key is just a pointer to a c-string

◆ rcutils_get_zero_initialized_hash_map()

rcutils_hash_map_t rcutils_get_zero_initialized_hash_map ( )

Return an empty hash_map struct.

This function returns an empty and zero initialized hash_map struct. All hash maps should be initialized with this or manually initialized before being used.


Attribute Adherence
Allocates Memory No
Thread-Safe No
Uses Atomics No
Lock-Free Yes

Example:

// Do not do this:
// rcutils_hash_map_t foo;
// rcutils_hash_map_fini(&foo); // undefined behavior!
// Do this instead:

◆ rcutils_hash_map_init()

rcutils_ret_t rcutils_hash_map_init ( rcutils_hash_map_t hash_map,
size_t  initial_capacity,
size_t  key_size,
size_t  data_size,
rcutils_hash_map_key_hasher_t  key_hashing_func,
rcutils_hash_map_key_cmp_t  key_cmp_func,
const rcutils_allocator_t allocator 
)

Initialize a rcutils_hash_map_t, allocating space for given capacity.

This function initializes the rcutils_hash_map_t with a given initial capacity for entries. Note this does not allocate space for keys or values in the hash_map, just the arrays of pointers to the keys and values. rcutils_hash_map_set() should still be used when assigning values.

The hash_map argument should point to allocated memory and should have been zero initialized with rcutils_get_zero_initialized_hash_map().


Attribute Adherence
Allocates Memory Yes
Thread-Safe No
Uses Atomics No
Lock-Free Yes

Example:

if (ret != RCUTILS_RET_OK) {
// ... do error handling
}
// ... use the hash_map and when done:
ret = rcutils_hash_map_fini(&hash_map);
if (ret != RCUTILS_RET_OK) {
// ... do error handling
}
Parameters
[in,out]hash_maprcutils_hash_map_t to be initialized
[in]initial_capacitythe amount of initial capacity for the hash_map
[in]key_sizethe size (in bytes) of the key used to index the data
[in]data_sizethe size (in bytes) of the data being stored
[in]key_hashing_funca function that returns a hashed value for a key
[in]key_cmp_funca function used to compare keys
[in]allocatorthe allocator to use through out the lifetime of the hash_map
Returns
RCUTILS_RET_OK if successful, or
RCUTILS_RET_INVALID_ARGUMENT for invalid arguments, or
RCUTILS_RET_BAD_ALLOC if memory allocation fails, or
RCUTILS_RET_STRING_MAP_ALREADY_INIT if alread initialized, or
RCUTILS_RET_ERROR if an unknown error occurs.

◆ rcutils_hash_map_fini()

rcutils_ret_t rcutils_hash_map_fini ( rcutils_hash_map_t hash_map)

Finalize the previously initialized hash_map struct.

This function will free any resources which were created when initializing or when calling rcutils_hash_map_set().


Attribute Adherence
Allocates Memory No
Thread-Safe No
Uses Atomics No
Lock-Free Yes
Parameters
[in,out]hash_maprcutils_hash_map_t to be finalized
Returns
RCUTILS_RET_OK if successful, or
RCUTILS_RET_INVALID_ARGUMENT for invalid arguments, or
RCUTILS_RET_ERROR if an unknown error occurs.

◆ rcutils_hash_map_get_capacity()

rcutils_ret_t rcutils_hash_map_get_capacity ( const rcutils_hash_map_t hash_map,
size_t *  capacity 
)

Get the current capacity of the hash_map.

This function will return the internal capacity of the hash_map, which is the number of buckets the hash_map uses to sort the keys. The capacity does not indicate how many key value pairs are stored in the hash_map, the rcutils_hash_map_get_size() function can provide that, nor the maximum number that can be stored without increasing the capacity. The capacity can be set initially with rcutils_hash_map_init().


Attribute Adherence
Allocates Memory No
Thread-Safe No
Uses Atomics No
Lock-Free Yes
Parameters
[in]hash_maprcutils_hash_map_t to be queried
[out]capacitycapacity of the hash_map
Returns
RCUTILS_RET_OK if successful, or
RCUTILS_RET_INVALID_ARGUMENT for invalid arguments, or
RCUTILS_RET_NOT_INITIALIZED if the hash_map is invalid, or
RCUTILS_RET_ERROR if an unknown error occurs.

◆ rcutils_hash_map_get_size()

rcutils_ret_t rcutils_hash_map_get_size ( const rcutils_hash_map_t hash_map,
size_t *  size 
)

Get the current size of the hash_map.

This function will return the internal size of the hash_map, which is the current number of key value pairs in the hash_map. The size is changed when calling rcutils_hash_map_set() or rcutils_hash_map_unset().


Attribute Adherence
Allocates Memory No
Thread-Safe No
Uses Atomics No
Lock-Free Yes
Parameters
[in]hash_maprcutils_hash_map_t to be queried
[out]sizesize of the hash_map
Returns
RCUTILS_RET_OK if successful, or
RCUTILS_RET_INVALID_ARGUMENT for invalid arguments, or
RCUTILS_RET_NOT_INITIALIZED if the hash_map is invalid, or
RCUTILS_RET_ERROR if an unknown error occurs.

◆ rcutils_hash_map_set()

rcutils_ret_t rcutils_hash_map_set ( rcutils_hash_map_t hash_map,
const void *  key,
const void *  value 
)

Set a key value pair in the hash_map, increasing capacity if necessary.

If the key already exists in the map then the value is updated to the new value provided. If it does not already exist then a new entry is added for the new key and value. The capacity will be increased if needed.


Attribute Adherence
Allocates Memory Yes
Thread-Safe No
Uses Atomics No
Lock-Free Yes
Parameters
[in,out]hash_maprcutils_hash_map_t to be updated
[in]keyhash_map key
[in]valuevalue for given hash_map key
Returns
RCUTILS_RET_OK if successful, or
RCUTILS_RET_INVALID_ARGUMENT for invalid arguments, or
RCUTILS_RET_BAD_ALLOC if memory allocation fails, or
RCUTILS_RET_NOT_INITIALIZED if the hash_map is invalid, or
RCUTILS_RET_ERROR if an unknown error occurs.

◆ rcutils_hash_map_unset()

rcutils_ret_t rcutils_hash_map_unset ( rcutils_hash_map_t hash_map,
const void *  key 
)

Unset a key value pair in the hash_map.

Unsets the key value pair in the hash_map and frees any internal resources allocated for the entry. This function will never decrease the capacity when removing keys. If the given key is not found, RCUTILS_RET_STRING_KEY_NOT_FOUND is returned.


Attribute Adherence
Allocates Memory No
Thread-Safe No
Uses Atomics No
Lock-Free Yes
Parameters
[in,out]hash_maprcutils_hash_map_t to be updated
[in]keyhash_map key, must be null terminated c string
Returns
RCUTILS_RET_OK if successful, or
RCUTILS_RET_INVALID_ARGUMENT for invalid arguments, or
RCUTILS_RET_NOT_INITIALIZED if the hash_map is invalid, or
RCUTILS_RET_STRING_KEY_NOT_FOUND if the key is not found in the map, or
RCUTILS_RET_ERROR if an unknown error occurs.

◆ rcutils_hash_map_key_exists()

bool rcutils_hash_map_key_exists ( const rcutils_hash_map_t hash_map,
const void *  key 
)

Get whether or not a key exists.

Returns true if the provided key exists in the hash_map or false if it does not or if the hash_map or key are invalid. In all cases no error message is set.


Attribute Adherence
Allocates Memory No
Thread-Safe No
Uses Atomics No
Lock-Free Yes
Parameters
[in]hash_maprcutils_hash_map_t to be searched
[in]keyhash_map key, must be null terminated c string
Returns
true if key is in the hash_map, or
false if key is not in the hash_map, or
false for invalid arguments, or
false if the hash_map is invalid.

◆ rcutils_hash_map_get()

rcutils_ret_t rcutils_hash_map_get ( const rcutils_hash_map_t hash_map,
const void *  key,
void *  data 
)

Get value given a key.

This function can be used to retrieve a shallow copy of the stored data. The data pointer must point to a section of memory large enough to copy the full size of the data being stored, which is specified when the hash_map in initialized.


Attribute Adherence
Allocates Memory No
Thread-Safe No
Uses Atomics No
Lock-Free Yes
Parameters
[in]hash_maprcutils_hash_map_t to be searched
[in]keyhash_map key to look up the data for
[out]dataA copy of the data stored in the map
Returns
RCUTILS_RET_OK if successful, or
RCUTILS_RET_INVALID_ARGUMENT for invalid arguments, or
RCUTILS_RET_NOT_INITIALIZED if the hash_map is invalid, or
RCUTILS_RET_NOT_FOUND if the key doesn't exist in the map, or
RCUTILS_RET_ERROR if an unknown error occurs.

◆ rcutils_hash_map_get_next_key_and_data()

rcutils_ret_t rcutils_hash_map_get_next_key_and_data ( const rcutils_hash_map_t hash_map,
const void *  previous_key,
void *  key,
void *  data 
)

Get the next key in the hash_map, unless NULL is given, then get the first key.

This function allows you to iteratively get each key/value pair in the hash_map.

If NULL is given for the previous_key, then the first key in the hash_map is returned. If that returned key is given as the previous_key for the next call to this function, then the next key in the hash_map is returned. If there are no more keys in the hash_map or if the given key is not in the hash_map, an error will be returned.

The order of the keys in the hash_map is arbitrary and if the hash_map is modified between calls to this function the behavior is undefined. If the hash_map is modified then iteration should begin again by passing NULL to get the first key again.


Attribute Adherence
Allocates Memory No
Thread-Safe No
Uses Atomics No
Lock-Free Yes

Example:

printf("entries in the hash_map:\n");
int key = 0, data = 0;
rcutils_ret_t status = rcutils_hash_map_get_next_key(&hash_map, NULL, &key, &data);
while (RCUTILS_RET_OK == status) {
printf("%i: %i\n", key, data);
status = rcutils_hash_map_get_next_key(&hash_map, &key, &key, &data);
}
Parameters
[in]hash_maprcutils_hash_map_t to be queried
[in]previous_keyNULL to get the first key or the previous key to get the next for
[out]keyA copy of the next key in the sequence
[out]dataA copy of the next data in the sequence
Returns
RCUTILS_RET_OK if successful, or
RCUTILS_RET_INVALID_ARGUMENT for invalid arguments, or
RCUTILS_RET_NOT_INITIALIZED if the hash_map is invalid, or
RCUTILS_RET_NOT_FOUND if the previous_key doesn't exist in the map, or
RCUTILS_RET_HASH_MAP_NO_MORE_ENTRIES if there is no more data beyound the previous_key, or
RCUTILS_RET_ERROR if an unknown error occurs.
rcutils_get_default_allocator
rcutils_allocator_t rcutils_get_default_allocator(void)
Return a properly initialized rcutils_allocator_t with default values.
rcutils_get_zero_initialized_hash_map
rcutils_hash_map_t rcutils_get_zero_initialized_hash_map()
Return an empty hash_map struct.
RCUTILS_RET_INVALID_ARGUMENT
#define RCUTILS_RET_INVALID_ARGUMENT
Invalid argument return code.
Definition: rcutils_ret.h:38
std::printf
T printf(T... args)
rcutils_ret_t
int rcutils_ret_t
The type that holds a return value for an rcutils operation.
Definition: rcutils_ret.h:26
RCUTILS_CHECK_ARGUMENT_FOR_NULL
#define RCUTILS_CHECK_ARGUMENT_FOR_NULL(argument, error_return_type)
Check an argument for a null value.
Definition: error_handling.h:204
RCUTILS_RET_NOT_INITIALIZED
#define RCUTILS_RET_NOT_INITIALIZED
Resource is not initialized.
Definition: rcutils_ret.h:42
rcutils_hash_map_fini
rcutils_ret_t rcutils_hash_map_fini(rcutils_hash_map_t *hash_map)
Finalize the previously initialized hash_map struct.
RCUTILS_RET_OK
#define RCUTILS_RET_OK
Successful operation.
Definition: rcutils_ret.h:29
rcutils_hash_map_init
rcutils_ret_t rcutils_hash_map_init(rcutils_hash_map_t *hash_map, size_t initial_capacity, size_t key_size, size_t data_size, rcutils_hash_map_key_hasher_t key_hashing_func, rcutils_hash_map_key_cmp_t key_cmp_func, const rcutils_allocator_t *allocator)
Initialize a rcutils_hash_map_t, allocating space for given capacity.
rcutils_hash_map_t
The structure holding the metadata for a hash map.
Definition: hash_map.h:35