rcutils  master
C API providing common utilities and data structures.
Macros | Functions
format_string.h File Reference
#include <string.h>
#include "rcutils/allocator.h"
#include "rcutils/macros.h"
#include "rcutils/visibility_control.h"

Go to the source code of this file.

Macros

#define rcutils_format_string(allocator, format_string, ...)   rcutils_format_string_limit(allocator, 2048, format_string, __VA_ARGS__)
 Return a newly allocated string, created with a format string. More...
 

Functions

char * rcutils_format_string_limit (rcutils_allocator_t allocator, size_t limit, const char *format_string,...)
 Return a newly allocated string, created with a format string up to a limit. More...
 

Macro Definition Documentation

◆ rcutils_format_string

#define rcutils_format_string (   allocator,
  format_string,
  ... 
)    rcutils_format_string_limit(allocator, 2048, format_string, __VA_ARGS__)

Return a newly allocated string, created with a format string.

This function is identical to rcutils_format_string_limit() except it has an implicit limit of 2048. For longer format strings, see rcutils_format_string_limit().

Function Documentation

◆ rcutils_format_string_limit()

char* rcutils_format_string_limit ( rcutils_allocator_t  allocator,
size_t  limit,
const char *  format_string,
  ... 
)

Return a newly allocated string, created with a format string up to a limit.

This function uses snprintf_s to determine the length of the resulting string and allocates storage for the resulting string, formats it, and then returns the result.

This function can fail and therefore return null if the format_string is null or if memory allocation fails or if snprintf_s fails. An error message is not set in any case.

Output strings that would be longer than the given limit are truncated.

All returned strings are null terminated.

The format string is passed to snprintf_s(), see its documentation for how to use the format string.

The returned string must be deallocated using the same allocator given once it is no longer needed.

See also
rcutils_snprintf()
Parameters
[in]allocatorthe allocator to use for allocation
[in]limitmaximum length of the output string
[in]format_stringformat of the output, must be null terminated
Returns
output string or null if there was an error