string_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 string_map.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	rcutils_string_map_t

Typedefs
typedef struct rcutils_string_map_t	rcutils_string_map_t

Functions
rcutils_string_map_t	rcutils_get_zero_initialized_string_map ()
	Return an empty string map struct. More...
rcutils_ret_t	rcutils_string_map_init (rcutils_string_map_t *string_map, size_t initial_capacity, rcutils_allocator_t allocator)
	Initialize a rcutils_string_map_t, allocating space for given capacity. More...
rcutils_ret_t	rcutils_string_map_fini (rcutils_string_map_t *string_map)
	Finalize the previously initialized string map struct. More...
rcutils_ret_t	rcutils_string_map_get_capacity (const rcutils_string_map_t *string_map, size_t *capacity)
	Get the current capacity of the string map. More...
rcutils_ret_t	rcutils_string_map_get_size (const rcutils_string_map_t *string_map, size_t *size)
	Get the current size of the string map. More...
rcutils_ret_t	rcutils_string_map_reserve (rcutils_string_map_t *string_map, size_t capacity)
	Reserve a given amount of capacity in the map. More...
rcutils_ret_t	rcutils_string_map_clear (rcutils_string_map_t *string_map)
	Remove all key value pairs from the map. More...
rcutils_ret_t	rcutils_string_map_set (rcutils_string_map_t *string_map, const char *key, const char *value)
	Set a key value pair in the map, increasing capacity if necessary. More...
rcutils_ret_t	rcutils_string_map_set_no_resize (rcutils_string_map_t *string_map, const char *key, const char *value)
	Set a key value pair in the map but only if the map has enough capacity. More...
rcutils_ret_t	rcutils_string_map_unset (rcutils_string_map_t *string_map, const char *key)
	Unset a key value pair in the map. More...
bool	rcutils_string_map_key_exists (const rcutils_string_map_t *string_map, const char *key)
	Get whether or not a key exists. More...
bool	rcutils_string_map_key_existsn (const rcutils_string_map_t *string_map, const char *key, size_t key_length)
	Get whether or not a key of known length exists. More...
const char *	rcutils_string_map_get (const rcutils_string_map_t *string_map, const char *key)
	Get value given a key. More...
const char *	rcutils_string_map_getn (const rcutils_string_map_t *string_map, const char *key, size_t key_length)
	Get value given a key and key length. More...
const char *	rcutils_string_map_get_next_key (const rcutils_string_map_t *string_map, const char *key)
	Get the next key in the map, unless NULL is given, then get the first key. More...
rcutils_ret_t	rcutils_string_map_copy (const rcutils_string_map_t *src_string_map, rcutils_string_map_t *dst_string_map)
	Copy all the key value pairs from one map into another, overwritting and resizing if needed. More...

Typedef Documentation

rcutils_string_map_t

typedef struct rcutils_string_map_t rcutils_string_map_t

Function Documentation

rcutils_get_zero_initialized_string_map()

rcutils_string_map_t rcutils_get_zero_initialized_string_map

(

)

Return an empty string map struct.

rcutils_string_map_init()

rcutils_ret_t rcutils_string_map_init	(	rcutils_string_map_t *	string_map,
		size_t	initial_capacity,
		rcutils_allocator_t	allocator
	)

Initialize a rcutils_string_map_t, allocating space for given capacity.

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

The string_map argument should point to allocated memory and should have been zero initialized with rcutils_get_zero_initialized_string_map(). For example:

rcutils_string_map_t string_map = rcutils_get_zero_initialized_string_map();
rcutils_ret_t ret =
  rcutils_string_map_init(&string_map, 10, rcutils_get_default_allocator());
if (ret != RCUTILS_RET_OK) {
  // ... do error handling
}
// ... use the string map and when done:
ret = rcutils_string_map_fini(&string_map);
if (ret != RCUTILS_RET_OK) {
  // ... do error handling
}

Parameters

[in,out]	string_map	rcutils_string_map_t to be initialized
[in]	initial_capacity	the amount of initial capacity for the string map
[in]	allocator	the allocator to use through out the lifetime of the 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_string_map_fini()

rcutils_ret_t rcutils_string_map_fini

(

rcutils_string_map_t *

string_map

)

Finalize the previously initialized string map struct.

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

Parameters

[in,out]

string_map

rcutils_string_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_string_map_get_capacity()

rcutils_ret_t rcutils_string_map_get_capacity	(	const rcutils_string_map_t *	string_map,
		size_t *	capacity
	)

Get the current capacity of the string map.

This function will return the internal capacity of the map, which is the maximum number of key value pairs the map could hold. The capacity can be set initially with rcutils_string_map_init() or with rcutils_string_map_reserve(). The capacity does not indicate how many key value paris are stored in the map, the rcutils_string_map_get_size() function can provide that.

Parameters

[in]	string_map	rcutils_string_map_t to be queried
[out]	capacity	capacity of the string map

Returns

RCUTILS_RET_OK if successful, or

RCUTILS_RET_INVALID_ARGUMENT for invalid arguments, or

RCUTILS_RET_STRING_MAP_INVALID if the string map is invalid, or

RCUTILS_RET_ERROR if an unknown error occurs

rcutils_string_map_get_size()

rcutils_ret_t rcutils_string_map_get_size	(	const rcutils_string_map_t *	string_map,
		size_t *	size
	)

Get the current size of the string map.

This function will return the internal size of the map, which is the current number of key value pairs in the map. The size is changed when calling rcutils_string_map_set_no_resize(), rcutils_string_map_set(), or rcutils_string_map_unset().

Parameters

[in]	string_map	rcutils_string_map_t to be queried
[out]	size	size of the string map

Returns

RCUTILS_RET_OK if successful, or

RCUTILS_RET_INVALID_ARGUMENT for invalid arguments, or

RCUTILS_RET_STRING_MAP_INVALID if the string map is invalid, or

RCUTILS_RET_ERROR if an unknown error occurs

rcutils_string_map_reserve()

rcutils_ret_t rcutils_string_map_reserve	(	rcutils_string_map_t *	string_map,
		size_t	capacity
	)

Reserve a given amount of capacity in the map.

Increases the capacity of the map to at least the given size.

If the current capacity is less than requested capacity then the capacity is increased using the allocator given during initialization of the map in rcutils_string_map_init(). If the requested capacity is less than the current capacity, the capacity may be reduced, but no existing key value pairs will be truncated to do so. In effect, the capacity will be shrunk to fit the number of items in map or the requested capacity, which ever is larger.

If recovering all resources is desired first call rcutils_string_map_clear() and then this function with a capacity of 0.

Parameters

[in,out]	string_map	rcutils_string_map_t to have space reserved in
[in]	capacity	requested size to reserve in the 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_INVALID if the string map is invalid, or

RCUTILS_RET_ERROR if an unknown error occurs

rcutils_string_map_clear()

rcutils_ret_t rcutils_string_map_clear

(

rcutils_string_map_t *

string_map

)

Remove all key value pairs from the map.

This function will remove all key value pairs from the map, and it will reclaim all resources allocated as a result of setting key value pairs. rcutils_string_map_fini() should still be called after this.

Parameters

[in,out]

string_map

rcutils_string_map_t to be cleared

Returns

RCUTILS_RET_OK if successful, or

RCUTILS_RET_INVALID_ARGUMENT for invalid arguments, or

RCUTILS_RET_STRING_MAP_INVALID if the string map is invalid, or

RCUTILS_RET_ERROR if an unknown error occurs

rcutils_string_map_set()

rcutils_ret_t rcutils_string_map_set	(	rcutils_string_map_t *	string_map,
		const char *	key,
		const char *	value
	)

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

The capacity will be increased if needed using rcutils_string_map_reserve(). Otherwise it is the same as rcutils_string_map_set_no_resize().

See also

rcutils_string_map_set_no_resize()

Parameters

[in,out]	string_map	rcutils_string_map_t to be updated
[in]	key	map key, must be null terminated c string
[in]	value	value for given 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_BAD_ALLOC if memory allocation fails, or

RCUTILS_RET_STRING_MAP_INVALID if the string map is invalid, or

RCUTILS_RET_ERROR if an unknown error occurs

rcutils_string_map_set_no_resize()

rcutils_ret_t rcutils_string_map_set_no_resize	(	rcutils_string_map_t *	string_map,
		const char *	key,
		const char *	value
	)

Set a key value pair in the map but only if the map has enough capacity.

If the map already contains the given key, the existing value will be replaced with the given value. If the map does not contain the given key, and the map has additional unused capacity, then it will store the given key and value in the map. If there is no unused capacity in the map, then RCUTILS_RET_NOT_ENOUGH_SPACE is returned.

The given key and value c strings are copied into the map, and so storage is allocated for them in the map when this function is called if necessary. The storage allocated for this purpose is reclaimed either when rcutils_string_map_fini() is called on this map or when using this function or rcutils_string_map_unset().

Any allocation that occurs in this functions uses the allocator of the map, which is given when the map is initialized in rcutils_string_map_init().

Parameters

[in,out]	string_map	rcutils_string_map_t to be updated
[in]	key	map key, must be null terminated c string
[in]	value	value for given 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_BAD_ALLOC if memory allocation fails, or

RCUTILS_RET_STRING_MAP_INVALID if the string map is invalid, or

RCUTILS_RET_NOT_ENOUGH_SPACE if map is full, or

RCUTILS_RET_ERROR if an unknown error occurs

rcutils_string_map_unset()

rcutils_ret_t rcutils_string_map_unset	(	rcutils_string_map_t *	string_map,
		const char *	key
	)

Unset a key value pair in the map.

The key needs to be a null terminated c string. If the given key is not found, RCUTILS_RET_STRING_KEY_NOT_FOUND is returned.

Parameters

[in,out]	string_map	rcutils_string_map_t to be updated
[in]	key	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_STRING_MAP_INVALID if the string map is invalid, or

RCUTILS_RET_STRING_KEY_NOT_FOUND if key not found, or

RCUTILS_RET_ERROR if an unknown error occurs

rcutils_string_map_key_exists()

bool rcutils_string_map_key_exists	(	const rcutils_string_map_t *	string_map,
		const char *	key
	)

Get whether or not a key exists.

The key needs to be a null terminated c string.

This function can fail and return false if the key is not found, or the string_map is NULL or invalid, or if the key is NULL. In all cases no error message is set.

Parameters

[in]	string_map	rcutils_string_map_t to be searched
[in]	key	map key, must be null terminated c string

Returns

true if key is in the map, or

false if key is not in the map, or

false for invalid arguments, or

false if the string map is invalid

rcutils_string_map_key_existsn()

bool rcutils_string_map_key_existsn	(	const rcutils_string_map_t *	string_map,
		const char *	key,
		size_t	key_length
	)

Get whether or not a key of known length exists.

Identical to rcutils_string_map_key_exists() but without relying on key to be a null terminated c string.

Parameters

[in]	string_map	rcutils_string_map_t to be searched
[in]	key	map key
[in]	key_length	map key length

Returns

true if key is in the map, or

false if key is not in the map, or

false for invalid arguments, or

false if the string map is invalid

rcutils_string_map_get()

const char* rcutils_string_map_get	(	const rcutils_string_map_t *	string_map,
		const char *	key
	)

Get value given a key.

The key needs to be a null terminated c string.

This function can fail, and therefore return NULL, if the key is not found, or the string_map is NULL or invalid, or if the key is NULL. In all cases no error message is set.

The returned value string is still owned by the map, and it should not be modified or free'd. This also means that the value pointer becomes invalid if either rcutils_string_map_clear() or rcutils_string_map_fini() are called or if the key value pair is updated or removed with one of rcutils_string_map_set() or rcutils_string_map_set_no_resize() or rcutils_string_map_unset().

Parameters

[in]	string_map	rcutils_string_map_t to be searched
[in]	key	map key, must be null terminated c string

Returns

value for the given key if successful, or

NULL for invalid arguments, or

NULL if the string map is invalid, or

NULL if key not found, or

NULL if an unknown error occurs

rcutils_string_map_getn()

const char* rcutils_string_map_getn	(	const rcutils_string_map_t *	string_map,
		const char *	key,
		size_t	key_length
	)

Get value given a key and key length.

Identical to rcutils_string_map_get() but without relying on key to be a null terminated c string.

Parameters

[in]	string_map	rcutils_string_map_t to be searched
[in]	key	map key
[in]	key_length	map key length

Returns

value for the given key if successful, or

NULL for invalid arguments, or

NULL if the string map is invalid, or

NULL if key not found, or

NULL if an unknown error occurs

rcutils_string_map_get_next_key()

const char* rcutils_string_map_get_next_key	(	const rcutils_string_map_t *	string_map,
		const char *	key
	)

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

This function allows you iteratively get each key in the map.

If NULL is given for the key, then the first key in the map is returned. If that returned key if given to the this function, then the next key in the map is returned. If there are no more keys in the map or if the given key is not in the map, NULL is returned.

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

This function operates based on the address of the pointer, you cannot pass a copy of a key to get the next key.

Example:

printf("keys in the map:\n");
const char * current_key = rcutils_string_map_get_next_key(&map, NULL);
while (current_key) {
  printf("  - %s\n", current_key);
  current_key = rcutils_string_map_get_next_key(&map, current_key);
}

NULL can also be returned if NULL is given for the string_map or if the string_map is invalid.

Parameters

[in]	string_map	rcutils_string_map_t to be queried
[in]	key	NULL to get the first key or the previous key to get the next

Returns

value for the given key if successful, or

NULL for invalid arguments, or

NULL if the string map is invalid, or

NULL if key not found, or

NULL if there are no more keys in the map, or

NULL if an unknown error occurs

rcutils_string_map_copy()

rcutils_ret_t rcutils_string_map_copy	(	const rcutils_string_map_t *	src_string_map,
		rcutils_string_map_t *	dst_string_map
	)

Copy all the key value pairs from one map into another, overwritting and resizing if needed.

If the destination string map does not have enough storage, then it is will be resized. If a key value pair exists in the destination map, its value will be replaced with the source map's value.

It is possible for only some of the values to be copied if an error happens during the copying process, e.g. if memory allocation fails.

Parameters

[in]	src_string_map	rcutils_string_map_t to be copied from
[in,out]	dst_string_map	rcutils_string_map_t to be copied to

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_INVALID if the string map is invalid, or

RCUTILS_RET_ERROR if an unknown error occurs