Go to the source code of this file.
|
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...
|
|
◆ rcutils_char_array_t
◆ rcutils_get_zero_initialized_char_array()
Return a zero initialized char array struct.
- Returns
- rcutils_char_array_t a zero initialized char array struct
◆ rcutils_char_array_init()
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_ARGUMENTS
if any arguments are invalid, or
-
'RCUTILS_RET_BAD_ALLOC
if no memory could be allocated correctly \return
RCUTILS_RET_ERROR` if an unexpected error occurs
◆ rcutils_char_array_fini()
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
-
- 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()
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()
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()
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()
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()
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()
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()
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