string_array.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 string_array.h:

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

Go to the source code of this file.

Classes
struct	rcutils_string_array_t

Typedefs
typedef struct rcutils_string_array_t	rcutils_string_array_t

Functions
rcutils_string_array_t	rcutils_get_zero_initialized_string_array (void)
	Return an empty string array struct. More...
rcutils_ret_t	rcutils_string_array_init (rcutils_string_array_t *string_array, size_t size, rcutils_allocator_t *allocator)
	Initialize a string array with a given size. More...
rcutils_ret_t	rcutils_string_array_fini (rcutils_string_array_t *string_array)
	Finalize a string array, reclaiming all resources. More...

Typedef Documentation

typedef struct rcutils_string_array_t rcutils_string_array_t

Function Documentation

rcutils_string_array_t rcutils_get_zero_initialized_string_array

(

void

)

Return an empty string array struct.

This function returns an empty and zero initialized string array struct. Calling rcutils_string_array_fini() on any non-initialized instance leads to undefined behavior. Every instance of string_array_t has to either be zero_initialized with this function or manually allocated.

Example:

rcutils_string_array_t foo;
rcutils_string_array_fini(&foo); // undefined behavior!

rcutils_string_array_t bar = rcutils_get_zero_initialized_string_array();
rcutils_string_array_fini(&bar); // ok

rcutils_ret_t rcutils_string_array_init	(	rcutils_string_array_t *	string_array,
		size_t	size,
		rcutils_allocator_t *	allocator
	)

Initialize a string array with a given size.

This function will initialize a given, zero initialized, string array to a given size.

Note that putting a string into the array gives owenship to the array.

Example:

rcutils_allocator_t allocator = rcutils_get_default_allocator();
rcutils_string_array_t string_array = rcutils_get_zero_initialized_string_array();
rcutils_ret_t ret = rcutils_string_array_init(&string_array, 2, &allocator);
if (ret != RCUTILS_RET_OK) {
  // ... error handling
}
string_array.data[0] = rcutils_strdup("Hello", &allocator);
string_array.data[1] = rcutils_strdup("World", &allocator);
ret = rcutils_string_array_fini(&string_array);

\param[inout] string_array object to be initialized
\param[in] size the size the array should be
\param[in] allocator to be used to allocate and deallocate memory
\return `RCUTILS_RET_OK` if successful, or
\return `RCUTILS_RET_INVALID_ARGUMENT` for invalid arguments, or
\return `RCUTILS_RET_BAD_ALLOC` if memory allocation fails, or
\return `RCUTILS_RET_ERROR` if an unknown error occurs

rcutils_ret_t rcutils_string_array_fini

(

rcutils_string_array_t *

string_array

)

Finalize a string array, reclaiming all resources.

This function reclaims any memory owned by the string array, including the strings it references.

The allocator used to initialize the string array is used to deallocate each string in the array and the array of strings itself.

Parameters

[in,out]

string_array

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