rcutils  master
C API providing common utilities and data structures.
Classes | Typedefs | Functions
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"

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, const 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

◆ rcutils_string_array_t

Function Documentation

◆ rcutils_get_zero_initialized_string_array()

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

rcutils_ret_t rcutils_string_array_init ( rcutils_string_array_t string_array,
size_t  size,
const 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_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_string_array_fini()

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