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"
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, 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...
 
rcutils_ret_t rcutils_string_array_cmp (const rcutils_string_array_t *lhs, const rcutils_string_array_t *rhs, int *res)
 Compare two string arrays. 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

◆ rcutils_string_array_cmp()

rcutils_ret_t rcutils_string_array_cmp ( const rcutils_string_array_t lhs,
const rcutils_string_array_t rhs,
int *  res 
)

Compare two string arrays.

The two string arrays are compared according to lexographical order.

Parameters
[in]sa0The first string array.
[in]sa1The second string array.
[out]resNegative value if lhs appears before rhs in lexographical order. Zero if lhs and rhs are equal. Positive value if lhs appears after rhs in lexographical order. \returnRCUTILS_RET_OKif successful, or \returnRCUTILS_RET_INVALID_ARGUMENTif any argument isNULL, or \returnRCUTILS_RET_INVALID_ARGUMENTiflhs->dataorrhs->dataisNULL, or \returnRCUTILS_RET_ERROR` if an unknown error occurs.