char_array.h File Reference

#include <stdarg.h>
#include "rcutils/allocator.h"
#include "rcutils/types/rcutils_ret.h"
#include "rcutils/visibility_control.h"

Include dependency graph for char_array.h:

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

Go to the source code of this file.

Classes
struct	rcutils_char_array_t

Typedefs
typedef struct rcutils_char_array_t	rcutils_char_array_t

Functions
rcutils_char_array_t	rcutils_get_zero_initialized_char_array (void)
	Return a zero initialized char array struct. More...
rcutils_ret_t	rcutils_char_array_init (rcutils_char_array_t *char_array, size_t buffer_capacity, const rcutils_allocator_t *allocator)
	Initialize a zero initialized char array struct. More...
rcutils_ret_t	rcutils_char_array_fini (rcutils_char_array_t *char_array)
	Finalize a char array struct. More...
rcutils_ret_t	rcutils_char_array_resize (rcutils_char_array_t *char_array, size_t new_size)
	Resize the internal buffer of the char array. More...
rcutils_ret_t	rcutils_char_array_expand_as_needed (rcutils_char_array_t *char_array, size_t new_size)
	Expand the internal buffer of the char array. More...
rcutils_ret_t	rcutils_char_array_vsprintf (rcutils_char_array_t *char_array, const char *format, va_list args)
	Produce output according to format and args. More...
rcutils_ret_t	rcutils_char_array_strncat (rcutils_char_array_t *char_array, const char *src, size_t n)
	Append a string (or part of it) to the string in buffer. More...
rcutils_ret_t	rcutils_char_array_strcat (rcutils_char_array_t *char_array, const char *src)
	Append a string to the string in buffer. More...
rcutils_ret_t	rcutils_char_array_memcpy (rcutils_char_array_t *char_array, const char *src, size_t n)
	Copy memory to buffer. More...
rcutils_ret_t	rcutils_char_array_strcpy (rcutils_char_array_t *char_array, const char *src)
	Copy a string to buffer. More...

Typedef Documentation

rcutils_char_array_t

typedef struct rcutils_char_array_t rcutils_char_array_t

Function Documentation

rcutils_get_zero_initialized_char_array()

rcutils_char_array_t rcutils_get_zero_initialized_char_array

(

void

)

Return a zero initialized char array struct.

Returns

rcutils_char_array_t a zero initialized char array struct

rcutils_char_array_init()

rcutils_ret_t rcutils_char_array_init	(	rcutils_char_array_t *	char_array,
		size_t	buffer_capacity,
		const rcutils_allocator_t *	allocator
	)

Initialize a zero initialized char array struct.

This function may leak if the char array struct is already pre-initialized. If the capacity is set to 0, no memory is allocated and the internal buffer is still NULL.

Parameters

char_array	a pointer to the to be initialized char array struct
buffer_capacity	the size of the memory to allocate for the byte stream
allocator	the allocator to use for the memory allocation

Returns

RCUTILS_RET_OK if successful, or

RCUTILS_RET_INVALID_ARGUMENTS if any arguments are invalid, or

'RCUTILS_RET_BAD_ALLOCif no memory could be allocated correctly \returnRCUTILS_RET_ERROR` if an unexpected error occurs

rcutils_char_array_fini()

rcutils_ret_t rcutils_char_array_fini

(

rcutils_char_array_t *

char_array

)

Finalize a char array struct.

Cleans up and deallocates any resources owned by rcutils_char_array_t. The array passed to this function needs to have been initialized by rcutils_char_array_init(). If .owns_buffer is false, this function has no effect because that implies that the char_array does not own the internal buffer. Passing an uninitialized instance to this function leads to undefined behavior.

Parameters

char_array

pointer to the rcutils_char_array_t to be cleaned up

Returns

RCUTILS_RET_OK if successful, or

RCUTILS_RET_INVALID_ARGUMENTS if the char_array argument is invalid

RCUTILS_RET_ERROR if an unexpected error occurs

rcutils_char_array_resize()

rcutils_ret_t rcutils_char_array_resize	(	rcutils_char_array_t *	char_array,
		size_t	new_size
	)

Resize the internal buffer of the char array.

The internal buffer of the char array can be resized dynamically if needed. If the new size is smaller than the current capacity, then the memory is truncated. Be aware, that this will deallocate the memory and therefore invalidates any pointers to this storage. If the new size is larger, new memory is getting allocated and the existing content is copied over. Note that if the array doesn't own the current buffer the function just allocates a new block of memory and copies the contents of the old buffer instead of resizing the existing buffer.

Parameters

char_array	pointer to the instance of rcutils_char_array_t which is being resized
new_size	the new size of the internal buffer

Returns

RCUTILS_RET_OK if successful, or

RCUTILS_RET_INVALID_ARGUMENT if new_size is set to zero

RCUTILS_RET_BAD_ALLOC if memory allocation failed, or

RCUTILS_RET_ERROR if an unexpected error occurs

rcutils_char_array_expand_as_needed()

rcutils_ret_t rcutils_char_array_expand_as_needed	(	rcutils_char_array_t *	char_array,
		size_t	new_size
	)

Expand the internal buffer of the char array.

This function is equivalent to rcutils_char_array_resize except that it resizes the internal buffer only when it is not big enough. If the buffer is already big enough for new_size, it returns RCUTILS_RET_OK without doing anything.

Parameters

char_array	pointer to the instance of rcutils_char_array_t which is being resized
new_size	the new size of the internal buffer

Returns

RCUTILS_RET_OK if successful, or

RCUTILS_RET_BAD_ALLOC if memory allocation failed, or

RCUTILS_RET_ERROR if an unexpected error occurs

rcutils_char_array_vsprintf()

rcutils_ret_t rcutils_char_array_vsprintf	(	rcutils_char_array_t *	char_array,
		const char *	format,
		va_list	args
	)

Produce output according to format and args.

This function is equivalent to vsprintf(char_array->buffer, format, args) except that the buffer grows as needed so a user doesn't have to deal with memory management. The va_list args will be cloned before being used, so a user can safely use it again after calling this function.

Parameters

char_array	pointer to the instance of rcutils_char_array_t which is being written to
format	the format string used by the underlying vsnprintf
args	the va_list used by the underlying vsnprintf

Returns

RCUTILS_RET_OK if successful, or

RCUTILS_RET_BAD_ALLOC if memory allocation failed, or

RCUTILS_RET_ERROR if an unexpected error occurs

rcutils_char_array_strncat()

rcutils_ret_t rcutils_char_array_strncat	(	rcutils_char_array_t *	char_array,
		const char *	src,
		size_t	n
	)

Append a string (or part of it) to the string in buffer.

This function treats the internal buffer as a string and appends the src string to it. If src is longer than n, n bytes will be used and an extra null byte will be appended. It is virtually equivalent to strncat(char_array->buffer, src, n) except that the buffer grows as needed so a user doesn't have to deal with memory management.

Parameters

char_array	pointer to the instance of rcutils_char_array_t which is being appended to
src	the string to be appended to the end of the string in buffer
n	it uses at most n bytes from the src string

Returns

RCUTILS_RET_OK if successful, or

RCUTILS_RET_BAD_ALLOC if memory allocation failed, or

RCUTILS_RET_ERROR if an unexpected error occurs

rcutils_char_array_strcat()

rcutils_ret_t rcutils_char_array_strcat	(	rcutils_char_array_t *	char_array,
		const char *	src
	)

Append a string to the string in buffer.

This function treats the internal buffer as a string and appends the src string to it. It is virtually equivalent to strcat(char_array->buffer, src) except that the buffer grows as needed. That is to say, a user can safely use it without doing calculation or checks on the sizes of the src and buffer.

Parameters

char_array	pointer to the instance of rcutils_char_array_t which is being appended to
src	the string to be appended to the end of the string in buffer

Returns

RCUTILS_RET_OK if successful, or

RCUTILS_RET_BAD_ALLOC if memory allocation failed, or

RCUTILS_RET_ERROR if an unexpected error occurs

rcutils_char_array_memcpy()

rcutils_ret_t rcutils_char_array_memcpy	(	rcutils_char_array_t *	char_array,
		const char *	src,
		size_t	n
	)

Copy memory to buffer.

This function is equivalent to memcpy(char_array->buffer, src, n) except that the buffer grows as needed so a user doesn't have to worry about overflow.

Parameters

char_array	pointer to the instance of rcutils_char_array_t which is being resized
src	the memory to be copied from
n	a total of n bytes will be copied

Returns

RCUTILS_RET_OK if successful, or

RCUTILS_RET_BAD_ALLOC if memory allocation failed, or

RCUTILS_RET_ERROR if an unexpected error occurs

rcutils_char_array_strcpy()

rcutils_ret_t rcutils_char_array_strcpy	(	rcutils_char_array_t *	char_array,
		const char *	src
	)

Copy a string to buffer.

This function is equivalent to strcpy(char_array->buffer, src) except that the buffer grows as needed so that src will fit without overflow.

Parameters

char_array	pointer to the instance of rcutils_char_array_t which is being copied to
src	the string to be copied from

Returns

RCUTILS_RET_OK if successful, or

RCUTILS_RET_BAD_ALLOC if memory allocation failed, or

RCUTILS_RET_ERROR if an unexpected error occurs