format_string.h File Reference

#include <string.h>
#include "rcutils/allocator.h"
#include "rcutils/macros.h"
#include "rcutils/visibility_control.h"

Include dependency graph for format_string.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,...) RCUTILS_ATTRIBUTE_PRINTF_FORMAT(3
	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]	allocator	the allocator to use for allocation
[in]	limit	maximum length of the output string
[in]	format_string	format of the output, must be null terminated

Returns

output string or null if there was an error