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:

  RCUTILS_CHECK_ARGUMENT_FOR_NULL(array_list, RCUTILS_RET_INVALID_ARGUMENT); \
  if (NULL == array_list->impl) { \
    RCUTILS_SET_ERROR_MSG("array_list is not initialized"); \
    return RCUTILS_RET_NOT_INITIALIZED; \
  }

Validates that an rcutils_array_list_t* points to a valid array list.

Parameters

[in]

array_list

A 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

typedef struct rcutils_array_list_t 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_t foo;
rcutils_array_list_fini(&foo); // undefined behavior!
 
rcutils_array_list_t bar = rcutils_get_zero_initialized_array_list();
rcutils_array_list_fini(&bar); // ok

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_allocator_t allocator = rcutils_get_default_allocator();
rcutils_array_list_t array_list = rcutils_get_zero_initialized_array_list();
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_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()

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

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

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

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

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

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