Go to the source code of this file.
|
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...
|
|
◆ 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
-
- Returns
- RCUTILS_RET_INVALID_ARGUMENT if map is null
-
RCUTILS_RET_NOT_INITIALIZED if map is not initialized
◆ rcutils_hash_map_t
◆ 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] | key | The 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] | val1 | The first value to compare |
[in] | val2 | The second value to compare |
- Returns
- A negative number if val1 < val2, or
-
A positve number if val1 > val2, or
-
Zero if val1 == val2
◆ 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()
Return an empty hash_map struct.
◆ rcutils_hash_map_init()
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:
- Parameters
-
[in,out] | hash_map | rcutils_hash_map_t to be initialized |
[in] | initial_capacity | the amount of initial capacity for the hash_map |
[in] | key_size | the size (in bytes) of the key used to index the data |
[in] | data_size | the size (in bytes) of the data being stored |
[in] | key_hashing_func | a function that returns a hashed value for a key |
[in] | key_cmp_func | a function used to compare keys |
[in] | allocator | the 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 already initialized, or
-
RCUTILS_RET_ERROR
if an unknown error occurs
◆ rcutils_hash_map_fini()
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
-
- 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()
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
-
- 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()
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
-
- 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()
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_map | rcutils_hash_map_t to be updated |
[in] | key | hash_map key |
[in] | value | value 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()
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_map | rcutils_hash_map_t to be updated |
[in] | key | hash_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_map | rcutils_hash_map_t to be searched |
[in] | key | hash_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()
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_map | rcutils_hash_map_t to be searched |
[in] | key | hash_map key to look up the data for |
[out] | data | A 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()
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);
printf(
"%i: %i\n", key, data);
status = rcutils_hash_map_get_next_key(&hash_map, &key, &key, &data);
}
- Parameters
-
[in] | hash_map | rcutils_hash_map_t to be queried |
[in] | previous_key | NULL to get the first key or the previous key to get the next for |
[out] | key | A copy of the next key in the sequence |
[out] | data | A 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
#define RCUTILS_CHECK_ARGUMENT_FOR_NULL(argument, error_return_type)
Check an argument for a null value.
Definition: error_handling.h:171
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.