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
	The structure holding the metadata for a char array. More...

Typedefs
typedef struct rcutils_char_array_t	rcutils_char_array_t
	The structure holding the metadata for a char array. More...

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

The structure holding the metadata for a char array.

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

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

Returns

RCUTILS_RET_OK if successful, or

RCUTILS_RET_INVALID_ARGUMENT if any arguments are invalid, or

RCUTILS_RET_BAD_ALLOC if no memory could be allocated correctly

RCUTILS_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

[in]

char_array

pointer to the rcutils_char_array_t to be cleaned up

Returns

RCUTILS_RET_OK if successful, or

RCUTILS_RET_INVALID_ARGUMENT 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

[in]	char_array	pointer to the instance of rcutils_char_array_t which is being resized
[in]	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

[in,out]	char_array	pointer to the instance of rcutils_char_array_t which is being resized
[in]	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

[in,out]	char_array	pointer to the instance of rcutils_char_array_t which is being written to
[in]	format	the format string used by the underlying vsnprintf
[in]	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

[in,out]	char_array	pointer to the instance of rcutils_char_array_t which is being appended to
[in]	src	the string to be appended to the end of the string in buffer
[in]	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

[in,out]	char_array	pointer to the instance of rcutils_char_array_t which is being appended to
[in]	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

[in,out]	char_array	pointer to the instance of rcutils_char_array_t which is being resized
[in]	src	the memory to be copied from
[in]	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

[in,out]	char_array	pointer to the instance of rcutils_char_array_t which is being copied to
[in]	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.