Printf utility function for strings

[relativityspace-jsmith]

I really love ETL strings as a safe alternative to C strings for embedded. (you would not BELIEVE how much dubiously safe C string code I had to review before we adopted ETL.) However, they do have a bit of an awkward limitation, which is that there's not an out of the box way to print formatted data into them. It's not difficult to do yourself, since you can pass the string's buffer in to sprintf(), but that opens the door for memory errors if you mess up your math.

At my company, we've created the following utility functions to make this easier:

#include <etl/string.h>

#include <cstdarg>
#include <cstdio>

/**
 * @brief Do a formatted print into an etl::string.
 *
 * This operation is safe: Printing will stop at the end of the provided string's memory, regardless of how
 * many characters were generated by the format string.
 *
 * @param[inout] str The string to print into
 * @param formatString Format string to use.
 * @param vlist Vararg list to print.
 *
 * @return false if the string was truncated, true otherwise (fit within the provided \c str).
 */
static inline bool vprintfInto(etl::istring & str, char const * formatString, va_list vlist)
{
    size_t bytesAttempted = vsnprintf(str.data(), str.capacity() + 1, formatString, vlist);
    str.trim_to_terminator();

    return bytesAttempted <= str.capacity();
}

/**
 * @brief Do a formatted print appending to the end of an etl::string.
 *
 * This operation is safe: Printing will stop at the end of the provided string's memory, regardless of how
 * many characters were generated by the format string.
 *
 * @param[inout] str The string to print into
 * @param formatString Format string to use.
 * @param vlist Vararg list to print.
 *
 * @return false if the string was truncated, true otherwise (fit within the provided \c str).
 */
static inline bool vprintfAppend(etl::istring & str, char const * formatString, va_list vlist)
{
    size_t stringSpaceLeftChars = str.capacity() - str.size();
    size_t bytesAttempted = vsnprintf(str.data_end(), stringSpaceLeftChars + 1, formatString, vlist);
    str.trim_to_terminator();

    return bytesAttempted <= stringSpaceLeftChars;
}


/**
 * @brief Do a formatted print into an etl::string.
 *
 * This operation is safe: Printing will stop at the end of the provided string's memory, regardless of how
 * many characters were generated by the format string.
 *
 * @param[inout] str The string to print into
 * @param formatString Format string to use.
 *
 * @return false if the string was truncated, true otherwise (fit within the provided \c str).
 */
static inline __attribute__((format (printf, 2, 3))) bool printfInto(etl::istring & str, char const * formatString, ...)
{
    va_list argList;
    va_start(argList, formatString);
    auto ret = vprintfInto(str, formatString, argList);
    va_end(argList);
    return ret;
}

/**
 * @brief Do a formatted print appending to the end of an etl::string.
 *
 * This operation is safe: Printing will stop at the end of the provided string's memory, regardless of how
 * many characters were generated by the format string.
 *
 * @param[inout] str The string to print into
 * @param formatString Format string to use.
 *
 * @return false if the string was truncated, true otherwise (fit within the provided \c str).
 */
static inline __attribute__((format (printf, 2, 3))) bool printfAppend(etl::istring & str, char const * formatString, ...)
{
    va_list argList;
    va_start(argList, formatString);
    auto ret = vprintfAppend(str, formatString, argList);
    va_end(argList);
    return ret;
}

This way we don't have to worry about passing the right buffer size into sprintf or checking the return values -- it just works. It's been MONTHS since I've had to read the manual page for snprintf() and I'm so happy.

(side note: As you probably know, the format attributes are GCC (+ clang?) specific and are for generating compiler warnings. They will probably need some preprocessor logic to disable them if they are not supported).

@jwellbelove Would you be interested in adding these functions in to ETL so that they're available for everyone? Feel free to add them based on this code, or if you tell me where to put them and what to call them, I can add them.

Thanks!

[jwellbelove]

Have you looked at etl::to_string and etl::string_stream?

[jwellbelove]

I think if I were to add printf style functionality I would prefer to adopt the type safe style of std::format and other third party libraries, such as {fmt}.

[relativityspace-jsmith]

I have heard (maybe falsely) that fmt carries a large code size cost due to its heavy use of templates. That's why I've never looked into using it on embedded before. Don't get me wrong, I am not a printf() crusader, but I don't really want to make compromises to avoid it either (e.g. larger code size and slower execution of fmt, or cancerous integer formatting associated with stringstreams).

If etl could provide a type-safe format string implementation that was suitable for embedded and didn't consume signficantly more resources than printf, that would be incredible!

[mike919192]

@relativityspace-jsmith

Just chipping in my 2 cents. fmt is quite embedded friendly, and I have done things like the following:

etl::string<63> bitVersion;

const auto result = fmt::format_to_n(bitVersion.data(), bitVersion.max_size(), 
                                     "Version{:x}.{:x}", MajorVersion(), MinorVersion());

*result.out = '\0';
bitVersion.trim_to_terminator();