fmt: A modern C++ formatting library

The {fmt} library is a modern C++ formatting library designed as a safe, fast, and extensible replacement for the printf family of functions and C++ iostreams.

Key capabilities include:

• Safety: Provides compile-time error reporting for invalid format strings (e.g., using a numeric specifier for a string) and prevents buffer overflows via automatic memory management.
• Extensibility: Supports standard types, containers, dates, and times out-of-the-box. Users can define custom formatting for their own types and enable compile-time checks for them.
• Performance: Significantly faster than iostreams and sprintf, particularly for numeric formatting, by minimizing dynamic memory allocations.
• Unicode Support: Provides portable UTF-8 and char string support across Linux, macOS, and Windows.
• Fast Compilation & Small Footprint: Uses type erasure to minimize template bloat and reduce compilation times. It also maintains a small binary footprint, with options to disable certain components (like floating-point formatting) for resource-constrained environments.
• Portability: A self-contained codebase with no external dependencies, requiring only a minimal subset of C++11 (compatible with GCC 4.9, Clang 3.6, MSVC 19.10, and later).

The {fmt} library uses format strings containing replacement fields delimited by braces {}. Text outside these braces is copied to the output unchanged.

Key Rules:

• Literal Braces: To output a single { or }, you must double them: {{ or }}.
• Argument Selection (arg_id):
  • Automatic Indexing: If no arg_id is provided (e.g., {}), arguments are consumed in left-to-right order.
  • Positional Reference: Use an integer (e.g., {0}, {1}) to select a specific argument by its position.
  • Named Reference: Use an identifier that matches a name provided via fmt::arg (e.g., {name}).
• Constraint: You cannot mix automatic indexing and explicit numeric IDs in the same format string; doing so results in a compile-time error or a format_error at runtime.
• Format Specification: A : following the arg_id introduces a format_spec (or chrono_format_spec) to control how the value is rendered.
• Nested Fields: You can use a replacement field inside a width or precision specification to provide those values from an integer argument at runtime. Nested fields must use an arg_id and cannot contain their own format_spec.

fmt::format("hello, {}", "world");
// Result: "hello, world"

fmt::format("{1}, {0}!", "world", "hello");
// Result: "hello, world!"

fmt::format("{greeting}, {name}!",
            fmt::arg("greeting", "hi"), fmt::arg("name", "fmt"));
// Result: "hi, fmt!"

You can format std::chrono duration and time point types, as well as std::tm, using a specific chrono format specification syntax. The syntax follows this pattern:

[[fill]align][width][.precision]chrono_specs

Where chrono_specs consists of conversion specifiers (starting with %) and literal characters.

Key Rules:

• Literal characters: Any character other than {, }, or % is copied unchanged to the output.
• Precision: Valid only for std::chrono::duration types with a floating-point representation type.
• Calendaric components: Specifiers like %d (day of month) are valid for std::tm and time points, but not for durations.
• Errors: If a specifier (like %a for weekday) is used on a value that does not contain that information, a fmt::format_error is thrown.

#include <fmt/chrono.h>

auto t = std::tm();
t.tm_year = 2010 - 1900;
t.tm_mon = 7;
t.tm_mday = 4;
t.tm_hour = 12;
t.tm_min = 15;
t.tm_sec = 58;
fmt::print("{:%Y-%m-%d %H:%M:%S}", t);
// Prints: 2010-08-04 12:15:58

When formatting range types (like std::vector, std::array, etc.), you can use a specific syntax to control how the container and its elements are displayed.

Syntax: [n][range_type][: range_underlying_spec]

• n option: Formats the range without the opening and closing brackets (e.g., h, e, l, l, o instead of [h, e, l, l, o]).
• range_type: Determines the presentation style:
  • none (default): Standard bracketed format.
  • 's': String format. The range is formatted as a single string. Requires the range elements to be character types.
  • '?s': Debug format. The range is formatted as an escaped string. Requires the range elements to be character types.
• range_underlying_spec: A specification applied to each individual element within the range. This is parsed based on the formatter of the element's type.

Constraints:

• The 'n' option and range_underlying_spec are mutually exclusive with 's' and '?s'.
• By default, ranges of characters or strings are printed escaped and quoted. However, if any range_underlying_spec is provided (even an empty one), the elements are printed according to that specification instead.

fmt::print("{}", std::vector{10, 20, 30});
// Output: [10, 20, 30]

fmt::print("{::#x}", std::vector{10, 20, 30});
// Output: [0xa, 0x14, 0x1e]

fmt::print("{:n}", std::vector{'h', 'e', 'l', 'l', 'o'});
// Output: 'h', 'e', 'l', 'l', 'o'

fmt::print("{:s}", std::vector{'h', 'e', 'l', 'l', 'o'});
// Output: "hello"

fmt::print("{:?s}", std::vector{'h', 'e', 'l', 'l', 'o', '\n'});
// Output: "hello\n"

fmt::print("{:n:f}", std::array{std::numbers::pi, std::numbers::e});
// Output: 3.141593, 2.718282