rcutils  master
C API providing common utilities and data structures.
Classes | Typedefs | Functions
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

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_arraya pointer to the to be initialized char array struct
[in]buffer_capacitythe size of the memory to allocate for the byte stream
[in]allocatorthe 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_arraypointer 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_arraypointer to the instance of rcutils_char_array_t which is being resized
[in]new_sizethe 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_arraypointer to the instance of rcutils_char_array_t which is being resized
[in]new_sizethe 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_arraypointer to the instance of rcutils_char_array_t which is being written to
[in]formatthe format string used by the underlying vsnprintf
[in]argsthe 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_arraypointer to the instance of rcutils_char_array_t which is being appended to
[in]srcthe string to be appended to the end of the string in buffer
[in]nit 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_arraypointer to the instance of rcutils_char_array_t which is being appended to
[in]srcthe 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_arraypointer to the instance of rcutils_char_array_t which is being resized
[in]srcthe memory to be copied from
[in]na 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_arraypointer to the instance of rcutils_char_array_t which is being copied to
[in]srcthe 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.