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

typedef struct rcutils_string_array_t 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_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_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_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);

Parameters

[in,out]	string_array	object to be initialized
[in]	size	the size the array should be
[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_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_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.

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]	lhs	The first string array.
[in]	rhs	The second string array.
[out]	res	Negative 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_array	object to be resized.
[in]	new_size	the 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]	lhs	pointer to the first string pointer.
[in]	rhs	pointer 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_array

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