rcutils
master
C API providing common utilities and data structures.
|
Go to the source code of this file.
|
rcutils_array_list_t | rcutils_get_zero_initialized_array_list (void) |
| Return an empty array_list struct. More...
|
|
rcutils_ret_t | rcutils_array_list_init (rcutils_array_list_t *array_list, size_t initial_capacity, size_t data_size, const rcutils_allocator_t *allocator) |
| Initialize an array list with a given initial capacity. More...
|
|
rcutils_ret_t | rcutils_array_list_fini (rcutils_array_list_t *array_list) |
| Finalize an array list, reclaiming all resources. More...
|
|
rcutils_ret_t | rcutils_array_list_add (rcutils_array_list_t *array_list, const void *data) |
| Adds an entry to the list. More...
|
|
rcutils_ret_t | rcutils_array_list_set (rcutils_array_list_t *array_list, size_t index, const void *data) |
| Sets an entry in the list to the provided data. More...
|
|
rcutils_ret_t | rcutils_array_list_remove (rcutils_array_list_t *array_list, size_t index) |
| Removes an entry in the list at the provided index. More...
|
|
rcutils_ret_t | rcutils_array_list_get (const rcutils_array_list_t *array_list, size_t index, void *data) |
| Retrieves an entry in the list at the provided index. More...
|
|
rcutils_ret_t | rcutils_array_list_get_size (const rcutils_array_list_t *array_list, size_t *size) |
| Retrieves the size of the provided array_list. More...
|
|
◆ ARRAY_LIST_VALIDATE_ARRAY_LIST
#define ARRAY_LIST_VALIDATE_ARRAY_LIST |
( |
|
array_list | ) |
|
Value:
if (NULL == array_list->impl) { \
RCUTILS_SET_ERROR_MSG("array_list is not initialized"); \
}
Validates that an rcutils_array_list_t* points to a valid array list.
- Parameters
-
- Returns
- RCUTILS_RET_INVALID_ARGUMENT if array_list is null
-
RCUTILS_RET_NOT_INITIALIZED if array_list is not initialized
◆ rcutils_array_list_t
◆ rcutils_get_zero_initialized_array_list()
Return an empty array_list struct.
This function returns an empty and zero initialized array_list struct. Calling rcutils_array_list_fini() on any non-initialized instance leads to undefined behavior. Every instance of array_list_t has to either be zero_initialized with this function or manually allocated.
Attribute | Adherence |
Allocates Memory | No |
Thread-Safe | Yes |
Uses Atomics | No |
Lock-Free | Yes |
Example:
◆ rcutils_array_list_init()
Initialize an array list with a given initial capacity.
This function will initialize a given, zero initialized, array_list to a given size.
Attribute | Adherence |
Allocates Memory | Yes |
Thread-Safe | No |
Uses Atomics | No |
Lock-Free | Yes |
Example:
}
int data = 42;
int out_data = 0;
data++;
assert(42 == out_data);
- Parameters
-
[in,out] | array_list | object to be initialized |
[in] | initial_capacity | the initial capacity to allocate in the list |
[in] | data_size | the size (in bytes) of the data object being stored in the list |
[in] | allocator | to be used to allocate and deallocate memory |
- 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_ERROR
if an unknown error occurs
◆ rcutils_array_list_fini()
Finalize an array list, reclaiming all resources.
This function reclaims any memory owned by the array list.
The allocator used to initialize the array list is used to deallocate each entry in the list and the list itself.
Attribute | Adherence |
Allocates Memory | No |
Thread-Safe | No |
Uses Atomics | No |
Lock-Free | Yes |
- Parameters
-
[in,out] | array_list | object 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_array_list_add()
Adds an entry to the list.
This function adds the provided data to the end of the list. A shallow copy of the provided data is made to store in the list instead of just storing the pointer to the provided data.
Attribute | Adherence |
Allocates Memory | Yes |
Thread-Safe | No |
Uses Atomics | No |
Lock-Free | Yes |
- Parameters
-
[in] | array_list | to add the data to |
[in] | data | a pointer to the data to add to the list |
- 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_ERROR
if an unknown error occurs
◆ rcutils_array_list_set()
Sets an entry in the list to the provided data.
This function sets the provided data at the specified index in the list. A shallow copy of the provided data is made to store in the list instead of just storing the pointer to the provided data.
Attribute | Adherence |
Allocates Memory | No |
Thread-Safe | No |
Uses Atomics | No |
Lock-Free | Yes |
- Parameters
-
[in] | array_list | to add the data to |
[in] | index | the position in the list to set the data |
[in] | data | a pointer to the data that will be set in the list |
- Returns
RCUTILS_RET_OK
if successful, or
-
RCUTILS_RET_INVALID_ARGUMENT
for invalid arguments, or
-
RCUTILS_RET_INVALID_ARGUMENT
if index out of bounds, or
-
RCUTILS_RET_ERROR
if an unknown error occurs
◆ rcutils_array_list_remove()
Removes an entry in the list at the provided index.
This function removes data from the list at the specified index. The capacity of the list will never decrease when entries are removed.
Attribute | Adherence |
Allocates Memory | No |
Thread-Safe | No |
Uses Atomics | No |
Lock-Free | Yes |
- Parameters
-
[in] | array_list | to add the data to |
[in] | index | the index of the item to remove from the list |
- Returns
RCUTILS_RET_OK
if successful, or
-
RCUTILS_RET_INVALID_ARGUMENT
for invalid arguments, or
-
RCUTILS_RET_INVALID_ARGUMENT
if index out of bounds, or
-
RCUTILS_RET_ERROR
if an unknown error occurs
◆ rcutils_array_list_get()
Retrieves an entry in the list at the provided index.
This function retrieves a copy of the data stored in the list at the provided index.
Attribute | Adherence |
Allocates Memory | No |
Thread-Safe | No |
Uses Atomics | No |
Lock-Free | Yes |
- Parameters
-
[in] | array_list | to add the data to |
[in] | index | the index at which to get the data |
[out] | data | a copy of the data stored in the list |
- Returns
RCUTILS_RET_OK
if successful, or
-
RCUTILS_RET_INVALID_ARGUMENT
for invalid arguments, or
-
RCUTILS_RET_ERROR
if an unknown error occurs
◆ rcutils_array_list_get_size()
Retrieves the size of the provided array_list.
This function retrieves the number of items in the provided array list
Attribute | Adherence |
Allocates Memory | No |
Thread-Safe | No |
Uses Atomics | No |
Lock-Free | Yes |
- Parameters
-
[in] | array_list | list to get the size of |
[out] | size | The number of items currently stored in the list |
- Returns
RCUTILS_RET_OK
if successful, or
-
RCUTILS_RET_INVALID_ARGUMENT
for invalid arguments, or
-
RCUTILS_RET_ERROR
if an unknown error occurs
rcutils_ret_t rcutils_array_list_get(const rcutils_array_list_t *array_list, size_t index, void *data)
Retrieves an entry in the list at the provided index.
Definition: array_list.h:32
rcutils_allocator_t rcutils_get_default_allocator(void)
Return a properly initialized rcutils_allocator_t with default values.
rcutils_ret_t rcutils_array_list_add(rcutils_array_list_t *array_list, const void *data)
Adds an entry to the list.
#define RCUTILS_RET_INVALID_ARGUMENT
Invalid argument return code.
Definition: rcutils_ret.h:31
rcutils_ret_t rcutils_array_list_init(rcutils_array_list_t *array_list, size_t initial_capacity, size_t data_size, const rcutils_allocator_t *allocator)
Initialize an array list with a given initial capacity.
int rcutils_ret_t
Definition: rcutils_ret.h:23
rcutils_array_list_t rcutils_get_zero_initialized_array_list(void)
Return an empty array_list struct.
Encapsulation of an allocator.
Definition: allocator.h:45
#define RCUTILS_CHECK_ARGUMENT_FOR_NULL(argument, error_return_type)
Check an argument for a null value.
Definition: error_handling.h:171
#define RCUTILS_RET_NOT_INITIALIZED
Resource is not initialized.
Definition: rcutils_ret.h:35
rcutils_ret_t rcutils_array_list_fini(rcutils_array_list_t *array_list)
Finalize an array list, reclaiming all resources.
#define RCUTILS_RET_OK
Definition: rcutils_ret.h:24