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

Go to the source code of this file.

Classes

struct  rcutils_array_list_t
 The structure holding the metadata for an array list. More...
 

Macros

#define ARRAY_LIST_VALIDATE_ARRAY_LIST(array_list)
 

Typedefs

typedef struct rcutils_array_list_t rcutils_array_list_t
 The structure holding the metadata for an array list. More...
 

Functions

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...
 

Macro Definition Documentation

◆ 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
[in]array_listA pointer to an rcutils_array_list_t
Returns
RCUTILS_RET_INVALID_ARGUMENT if array_list is null
RCUTILS_RET_NOT_INITIALIZED if array_list is not initialized

Typedef Documentation

◆ rcutils_array_list_t

The structure holding the metadata for an array list.

Function Documentation

◆ rcutils_get_zero_initialized_array_list()

rcutils_array_list_t rcutils_get_zero_initialized_array_list ( void  )

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

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.

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:

rcutils_ret_t ret = rcutils_array_list_init(&array_list, 2, sizeof(int), &allocator);
if (ret != RCUTILS_RET_OK) {
// ... error handling
}
int data = 42;
int out_data = 0;
ret = rcutils_array_list_add(&array_list, &data);
data++;
ret = rcutils_array_list_get(&array_list, 0, &out_data);
assert(42 == out_data);
ret = rcutils_array_list_fini(&array_list);
Parameters
[in,out]array_listobject to be initialized
[in]initial_capacitythe initial capacity to allocate in the list
[in]data_sizethe size (in bytes) of the data object being stored in the list
[in]allocatorto 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()

rcutils_ret_t rcutils_array_list_fini ( rcutils_array_list_t array_list)

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_listobject 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()

rcutils_ret_t rcutils_array_list_add ( rcutils_array_list_t array_list,
const void *  data 
)

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_listto add the data to
[in]dataa 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()

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.

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_listto add the data to
[in]indexthe position in the list to set the data
[in]dataa 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()

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.

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_listto add the data to
[in]indexthe 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()

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.

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_listto add the data to
[in]indexthe index at which to get the data
[out]dataa 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()

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.

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_listlist to get the size of
[out]sizeThe 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_array_list_get
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.
rcutils_array_list_t
The structure holding the metadata for an array list.
Definition: array_list.h:35
rcutils_get_default_allocator
rcutils_allocator_t rcutils_get_default_allocator(void)
Return a properly initialized rcutils_allocator_t with default values.
rcutils_array_list_add
rcutils_ret_t rcutils_array_list_add(rcutils_array_list_t *array_list, const void *data)
Adds an entry to the list.
RCUTILS_RET_INVALID_ARGUMENT
#define RCUTILS_RET_INVALID_ARGUMENT
Invalid argument return code.
Definition: rcutils_ret.h:38
rcutils_array_list_init
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.
rcutils_ret_t
int rcutils_ret_t
The type that holds a return value for an rcutils operation.
Definition: rcutils_ret.h:26
rcutils_get_zero_initialized_array_list
rcutils_array_list_t rcutils_get_zero_initialized_array_list(void)
Return an empty array_list struct.
rcutils_allocator_t
Encapsulation of an allocator.
Definition: allocator.h:47
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_array_list_fini
rcutils_ret_t rcutils_array_list_fini(rcutils_array_list_t *array_list)
Finalize an array list, reclaiming all resources.
RCUTILS_RET_OK
#define RCUTILS_RET_OK
Successful operation.
Definition: rcutils_ret.h:29