rcutils
master
C API providing common utilities and data structures.
|
#include <string.h>
#include "rcutils/allocator.h"
#include "rcutils/types/rcutils_ret.h"
#include "rcutils/macros.h"
#include "rcutils/visibility_control.h"
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... | |
#define HASH_MAP_VALIDATE_HASH_MAP | ( | map | ) |
Validates that an rcutils_hash_map_t* points to a valid hash map.
[in] | map | A pointer to an rcutils_hash_map_t |
typedef struct rcutils_hash_map_t rcutils_hash_map_t |
The structure holding the metadata for a hash map.
typedef size_t(* rcutils_hash_map_key_hasher_t) (const void *) |
The function signature for a key hashing function.
[in] | key | The key that needs to be hashed |
typedef int(* rcutils_hash_map_key_cmp_t) (const void *, const void *) |
The function signature for a key comparison function.
[in] | val1 | The first value to compare |
[in] | val2 | The second value to compare |
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
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_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:
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:
[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 |
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 |
[in,out] | hash_map | rcutils_hash_map_t to be finalized |
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 |
[in] | hash_map | rcutils_hash_map_t to be queried |
[out] | capacity | capacity of the hash_map |
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 |
[in] | hash_map | rcutils_hash_map_t to be queried |
[out] | size | size of the hash_map |
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 |
[in,out] | hash_map | rcutils_hash_map_t to be updated |
[in] | key | hash_map key |
[in] | value | value for given hash_map key |
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 |
[in,out] | hash_map | rcutils_hash_map_t to be updated |
[in] | key | hash_map key, must be null terminated c string |
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 |
[in] | hash_map | rcutils_hash_map_t to be searched |
[in] | key | hash_map key, must be null terminated c string |
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_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 |
[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 |
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:
[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 |