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/error_handling.h"
#include "rcutils/macros.h"
#include "rcutils/qsort.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
 The structure holding the metadata for a string array. More...
 

Typedefs

typedef struct rcutils_string_array_t rcutils_string_array_t
 The structure holding the metadata for a string array. More...
 

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...
 
rcutils_ret_t rcutils_string_array_resize (rcutils_string_array_t *string_array, size_t new_size)
 Resize a string array, reclaiming removed resources. More...
 
int rcutils_string_array_sort_compare (const void *lhs, const void *rhs)
 Lexicographic comparer for pointers to string pointers. More...
 
rcutils_ret_t rcutils_string_array_sort (rcutils_string_array_t *string_array)
 Sort a string array according to lexicographical order. More...
 

Typedef Documentation

◆ rcutils_string_array_t

The structure holding the metadata for a string array.

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);
Parameters
[in,out]string_arrayobject to be initialized
[in]sizethe size the array should be
[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_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 lexicographical order.

Parameters
[in]lhsThe first string array.
[in]rhsThe second string array.
[out]resNegative value if lhs appears before rhs in lexicographical order. Zero if lhs and rhs are equal. Positive value if lhs appears after rhs in lexographical order.
Returns
RCUTILS_RET_OK if successful, or
RCUTILS_RET_INVALID_ARGUMENT if any argument is NULL, or \return #RCUTILS_RET_INVALID_ARGUMENT iflhs->dataorrhs->dataisNULL, or
RCUTILS_RET_ERROR if an unknown error occurs.

◆ rcutils_string_array_resize()

rcutils_ret_t rcutils_string_array_resize ( rcutils_string_array_t string_array,
size_t  new_size 
)

Resize a string array, reclaiming removed resources.

This function changes the size of an existing string array. If the new size is larger, new entries are added to the end of the array and are zero- initialized. If the new size is smaller, entries are removed from the end of the array and their resources reclaimed.

Note:
Resizing to 0 is not a substitute for calling rcutils_string_array_fini.
Note:
If this function fails, string_array remains unchanged and should still be reclaimed with rcutils_string_array_fini.
Parameters
[in,out]string_arrayobject to be resized.
[in]new_sizethe size the array should be changed to.
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_string_array_sort_compare()

int rcutils_string_array_sort_compare ( const void *  lhs,
const void *  rhs 
)

Lexicographic comparer for pointers to string pointers.

This functions compares pointers to string pointers lexicographically ascending.

Parameters
[in]lhspointer to the first string pointer.
[in]rhspointer to the second string pointer.
Returns
<0 if lhs is lexicographically lower, or
0 if the strings are the same, or
>0 if lhs is lexicographically higher.

◆ rcutils_string_array_sort()

rcutils_ret_t rcutils_string_array_sort ( rcutils_string_array_t string_array)
inline

Sort a string array according to lexicographical order.

This function changes the order of the entries in a string array so that they are in lexicographically ascending order. Empty entries are placed at the end of the array.

Parameters
[in,out]string_arrayobject whose elements should be sorted.
Returns
RCUTILS_RET_OK if successful, or
RCUTILS_RET_INVALID_ARGUMENT for invalid arguments, or
RCUTILS_RET_ERROR if an unknown error occurs.
rcutils_get_default_allocator
rcutils_allocator_t rcutils_get_default_allocator(void)
Return a properly initialized rcutils_allocator_t with default values.
rcutils_string_array_t
The structure holding the metadata for a string array.
Definition: string_array.h:35
rcutils_strdup
char * rcutils_strdup(const char *str, rcutils_allocator_t allocator)
Return a duplicated string with an allocator, or null if an error occurs.
rcutils_ret_t
int rcutils_ret_t
The type that holds a return value for an rcutils operation.
Definition: rcutils_ret.h:26
rcutils_string_array_fini
rcutils_ret_t rcutils_string_array_fini(rcutils_string_array_t *string_array)
Finalize a string array, reclaiming all resources.
rcutils_allocator_t
Encapsulation of an allocator.
Definition: allocator.h:47
rcutils_get_zero_initialized_string_array
rcutils_string_array_t rcutils_get_zero_initialized_string_array(void)
Return an empty string array struct.
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.
RCUTILS_RET_OK
#define RCUTILS_RET_OK
Successful operation.
Definition: rcutils_ret.h:29
rcutils_string_array_t::data
char ** data
The allocated memory for the string array.
Definition: string_array.h:41