Format & Print

Overview

ETL provides text formatting facilities modelled on C++20 std::format and C++23 std::print. They allow type-safe, positional formatting of values into strings or directly to a character output device — without heap allocation.

Minimum language standard: C++11 (ETL_USING_CPP11).

Headers:

etl::format_to

Generic output-iterator overload

template <typename OutputIt, class... Args>
OutputIt format_to(OutputIt out, format_string<Args...> fmt, Args&&... args);

Formats args according to the format string fmt and writes the result through the output iterator out. Returns an iterator past the last character written.

OutputIt can be any output iterator whose dereferenced type is assignable from char, for example etl::istring::iterator or etl::back_insert_iterator<etl::istring>.

etl::string<100> s;

// Using a raw iterator — you must resize the string yourself
etl::istring::iterator result = etl::format_to(s.begin(), "{0} {1}", 34, 56);
s.uninitialized_resize(static_cast<size_t>(result - s.begin()));
// s == "34 56"

// Using a back_insert_iterator — string grows automatically
s.clear();
etl::back_insert_iterator<etl::istring> it(s);
etl::format_to(it, "{} {}", 65, 34);
// s == "65 34"

etl::istring& overload (ETL-specific)

template<class... Args>
etl::istring::iterator format_to(etl::istring& out,
                                  format_string<Args...> fmt,
                                  Args&&... args);

Convenience overload that writes into an etl::istring (or any derived etl::string<N>). The string is automatically resized to the number of characters written, up to out.max_size(). Returns an iterator past the last character written.

etl::string<100> s;
etl::format_to(s, "Hello, {}!", "world");
// s == "Hello, world!"

etl::format_to_n

template<typename OutputIt, class... Args>
OutputIt format_to_n(OutputIt out, size_t n,
                     format_string<Args...> fmt, Args&&... args);

Like format_to, but writes at most n characters. Characters beyond the limit are silently discarded.

etl::string<10> s = "abcdefghij";
etl::format_to_n(s.begin(), 3, "xy{}", 123);
// s == "xy1defghij"   (only 3 chars written)

etl::formatted_size

template<class... Args>
size_t formatted_size(format_string<Args...> fmt, Args&&... args);

Returns the total number of characters that format_to would produce, without actually writing anything. Useful for pre-computing buffer sizes.

size_t n;
n = etl::formatted_size("");            // 0
n = etl::formatted_size("{}", "");      // 0
n = etl::formatted_size("xyz{}", 12);  // 5
n = etl::formatted_size("{}", "abc");   // 3

etl::print and etl::println

Declared in etl/print.h.

etl::print

template<class... Args>
void print(etl::format_string<Args...> fmt, Args&&... args);

Formats the arguments and outputs each character by calling etl_putchar().

etl::println

// With arguments — prints formatted text followed by '\n'
template<class... Args>
void println(etl::format_string<Args...> fmt, Args&&... args);

// Without arguments — prints a bare newline
void println();

Implementing etl_putchar

etl/print.h declares (but does not define) the following C-linkage function:

extern "C" void etl_putchar(int c);

You must provide a definition in your project. The int parameter follows the convention of the standard putchar() and carries a single char value.

Typical implementations forward to a UART, a debug probe, putchar, or any other single-character output sink:

// Example: forward to standard putchar
extern "C" void etl_putchar(int c)
{
  putchar(c);
}

Example

etl::print("x = {}, y = {}\n", 10, 20);   // "x = 10, y = 20\n"
etl::println("Hello, {}!", "world");        // "Hello, world!\n"
etl::println();                             // "\n"

Format String Syntax

A format string is ordinary text with replacement fields delimited by braces:

"literal text {} more text {1:>10} end"

Replacement field grammar

replacement_field ::= '{' [arg_id] [':' format_spec] '}'
arg_id            ::= integer            // e.g. 0, 1, 2 …
format_spec       ::= [[fill]align] [sign] ['#'] ['0'] [width] ['.' precision] ['L'] [type]

Examples

etl::format_to(s, "{:>10}", 42);       // "        42"
etl::format_to(s, "{:*^10}", 42);      // "****42****"
etl::format_to(s, "{:+05d}", 67);      // "+00067"
etl::format_to(s, "{:#x}", 0x3f4);     // "0x3f4"
etl::format_to(s, "{:.3s}", "abcdef"); // "abc"
etl::format_to(s, "{1} {0}", 1, 2);    // "2 1"

Supported Argument Types

The core set of formattable types (matching std::basic_format_arg):

Implicit conversions

Types not listed above are converted automatically before formatting:

Presentation Types per Argument Kind

Integers (int, unsigned int, long long int, unsigned long long int)

With #: prefixes 0x/0X, 0b/0B, or leading 0 for octal.

Characters (char, signed char, unsigned char)

Booleans (bool)

Strings (const char*, etl::string_view, etl::string<N>)

Width and precision apply: width sets the minimum field width; precision (.N) truncates the string to at most N characters.

etl::format_to(s, "{:>10s}", "data1");    // "     data1"
etl::format_to(s, "{:.3s}", "abcdef");    // "abc"
etl::format_to(s, ".{:^8.3s}!", "data1"); // ".  dat   !"

Pointers (const void*)

Floating-point (float, double, long double)

Requires ETL_USING_FORMAT_FLOATING_POINT.

nan, inf (lowercase for e/f/g/a, uppercase for E/F/G/A).

Formatting User-Defined Types

Custom types can be made formattable by providing a specialisation of etl::formatter<T>, mirroring the std::formatter<T> mechanism. Once a specialisation is in scope, values of that type can be passed to format_to, format_to_n, formatted_size, print, and println exactly like the built-in types.

The etl::formatter primary template

template <class T, class CharT = char>
struct formatter;

The primary template is empty. A type T becomes formattable when you provide a specialisation (in namespace etl) that defines two member functions:

Context types

Example

// A simple user-defined type.
struct coordinate
{
  int x;
  int y;
};

// Specialise etl::formatter for it.  Here format() simply delegates to
// etl::format_to, writing the two members as "(x, y)".
namespace etl
{
  template <>
  struct formatter<coordinate>
  {
    format_parse_context::iterator parse(format_parse_context& parse_ctx)
    {
      return parse_ctx.begin();
    }

    template <class OutputIt>
    typename format_context<OutputIt>::iterator format(const coordinate& c, format_context<OutputIt>& fmt_ctx)
    {
      return etl::format_to(fmt_ctx.out(), "({}, {})", c.x, c.y);
    }
  };
}

With the specialisation in scope, coordinate behaves like any other argument:

etl::string<100> s;
coordinate c{3, 7};

etl::format_to(s, "{}", c);                // "(3, 7)"
etl::format_to(s, "point={}", c);         // "point=(3, 7)"
etl::format_to(s, "{0} and {0}", c);      // "(3, 7) and (3, 7)"
etl::format_to(s, "{} {} {}", 'a', c, 5); // "a (3, 7) 5"
etl::formatted_size("{}", c);             // 6

How it works

When an argument type provides an etl::formatter<T> specialisation, ETL stores the value type-erased inside basic_format_arg::handle rather than in one of the built-in alternatives. During formatting the handle invokes the formatter’s parse and format members. Detection is automatic: a type is treated as a custom type when etl::formatter<T> exposes a callable parse() member, so no opt-in trait or registration is required.

Escape Sequences and Literal Braces

Literal braces

Because { and } delimit replacement fields, they must be escaped by doubling:

etl::format_to(s, "abc{{def");  // "abc{def"
etl::format_to(s, "}}abc");     // "}abc"

Debug / escaped presentation (?)

The ? type specifier produces a debug representation:

• Characters are wrapped in single quotes with C-style escape sequences:

  Character	Output
  \t	'\\t'
  \n	'\\n'
  \r	'\\r'
  "	'\\\"'
  '	'\\''
  \\	'\\\\'

• Strings are wrapped in double quotes with the same escape sequences:

  etl::format_to(s, "{:?}", "data1\n");  // "\"data1\\n\""
  

Error Handling

Invalid format strings cause an etl::bad_format_string_exception (derived from etl::format_exception, which is derived from etl::exception).

Common error conditions:

etl::string<100> s;
// These all throw etl::bad_format_string_exception:
etl::format_to(s, "a{b}",  1);      // bad index spec
etl::format_to(s, "a{b",   1);      // closing brace missing
etl::format_to(s, "a}b");           // unescaped }
etl::format_to(s, "{:d}", sv);      // invalid type for string_view

Note: On C++20 and later, compile-time format string validation through consteval is planned but not yet fully implemented.

Differences from std::format