C++20/23 Format Library: Modern String Formatting in C++

String formatting is a fundamental task in programming, used for logging, user interfaces, data serialization, and debugging. For decades, C++ developers relied on printf (inherited from C) or iostreams (std::cout, std::stringstream). Both have drawbacks: printf is type-unsafe and error-prone; iostreams are verbose and slow. The C++20 standard introduced the format library (std::format), inspired by Python's str.format and the {fmt} library. It combines the best of both worlds: type safety, performance, and expressive syntax. C++23 further improves it with std::print and std::println. This tutorial covers everything you need to use the format library effectively in production code, from basic usage to custom formatters and debugging.

Basic Usage of std::format

The std::format function takes a format string and a variable number of arguments. Placeholders are denoted by curly braces {}. The simplest form is {} which outputs the argument in its default format. Arguments are indexed automatically starting from 0. You can also use explicit indices like {0}, {1} to reorder arguments. Named arguments are not supported directly, but you can use std::format with a map or tuple.

Example: std::format("Hello, {}!", "world") returns "Hello, world!".

Format specifiers follow a colon after the index: {0:spec}. Common specifiers include d for decimal, x for hex, f for fixed-point, e for scientific, and s for string. Width and precision are specified as {0:10} (minimum width 10) or {0:.2f} (2 decimal places). Alignment is done with <, >, ^ for left, right, center.

#include <format>
#include <iostream>

int main() {
    std::string name = "Alice";
    int age = 30;
    double pi = 3.1415926535;

    // Basic
    std::cout << std::format("Name: {}, Age: {}\n", name, age);

    // Positional
    std::cout << std::format("{1}, {0}\n", name, age);

    // Width and alignment
    std::cout << std::format("|{:10}|{:>10}|\n", name, age);

    // Precision
    std::cout << std::format("Pi: {:.2f}\n", pi);

    // Hex
    std::cout << std::format("Hex: {:x}\n", 255);

    return 0;
}

Format Specifiers in Depth

Format specifiers follow the pattern: [[fill]align][sign][#][0][width][.precision][type]. Fill character defaults to space. Align: < (left), > (right), ^ (center). Sign: + (always show sign), - (only negative), space (space for positive). # adds alternate form (e.g., 0x for hex). 0 pads with zeros. Width is minimum field width. Precision for floating-point is number of digits after decimal; for strings, maximum length. Type: d, i, u, o, x, X, f, F, e, E, g, G, a, A, s, c, p.

#include <format>
#include <iostream>

int main() {
    int n = 42;
    double d = -3.14159;
    std::string s = "Hello, World!";

    // Sign and fill
    std::cout << std::format("{:+05d}\n", n);   // +0042
    std::cout << std::format("{:05d}\n", n);    // 00042
    std::cout << std::format("{:<+10.2f}\n", d); // -3.14     

    // Alternate forms
    std::cout << std::format("{:#x}\n", 255);   // 0xff
    std::cout << std::format("{:#o}\n", 255);   // 0377

    // String precision
    std::cout << std::format("{:.5s}\n", s);    // Hello

    // Center
    std::cout << std::format("{:^20}\n", "centered");

    return 0;
}

Formatting User-Defined Types

To format custom types, specialize std::formatter for your type. The specialization must provide two member functions: parse() and format(). parse() reads the format specifier from the format string (between { and :). format() writes the formatted output to the output iterator. The parse method should return an iterator past the parsed specifier. The format method uses the specifier to format the value.

Example: Format a Point struct as (x, y). Support precision for coordinates.

#include <format>
#include <iostream>

struct Point {
    double x, y;
};

template<>
struct std::formatter<Point> {
    char presentation = 'f';
    int precision = 2;

    auto parse(format_parse_context& ctx) {
        auto it = ctx.begin();
        if (it != ctx.end() && *it == 'f') {
            presentation = 'f';
            ++it;
        }
        if (it != ctx.end() && *it == ':') {
            ++it;
            auto [end, ec] = std::from_chars(it, ctx.end(), precision);
            if (ec == std::errc()) it = end;
        }
        return it;
    }

    auto format(const Point& p, format_context& ctx) const {
        return std::format_to(ctx.out(), "({:.{}}, {:.{}})", p.x, precision, p.y, precision);
    }
};

int main() {
    Point p{3.14159, 2.71828};
    std::cout << std::format("{}\n", p);       // (3.14, 2.72)
    std::cout << std::format("{:f:4}\n", p);   // (3.1416, 2.7183)
    return 0;
}

Performance and std::format_to

std::format returns a std::string, which involves allocation. For performance-critical code, use std::format_to which writes to an output iterator. You can write to a pre-allocated buffer, a file, or a custom sink. std::format_to returns an iterator past the last written character. Also consider using std::formatted_size to compute the required buffer size without formatting.

Example: Write formatted output to a fixed-size buffer.

#include <format>
#include <iostream>
#include <array>

int main() {
    std::array<char, 64> buffer;
    auto it = std::format_to(buffer.begin(), "Value: {:.2f}", 3.14159);
    *it = '\0'; // null-terminate
    std::cout << buffer.data() << '\n';

    // Using formatted_size
    auto size = std::formatted_size("Hello, {}!", "world");
    std::cout << "Size: " << size << '\n';

    return 0;
}

Locale and Unicode Support

std::format respects the global locale for formatting numbers (e.g., thousands separator). Use the 'L' specifier to enable locale-specific formatting. For example, {:L} formats an integer with locale-specific digit grouping. Unicode support is limited; std::format works with char and wchar_t strings. For UTF-8, use std::string (char8_t in C++20). However, width and alignment may not correctly handle multi-byte characters. Consider using libraries like fmt for full Unicode support.

Example: Locale-aware formatting.

#include <format>
#include <iostream>
#include <locale>

int main() {
    std::locale::global(std::locale("en_US.UTF-8"));
    int big = 1234567;
    std::cout << std::format("Default: {}\n", big);
    std::cout << std::format("Locale: {:L}\n", big);
    return 0;
}

Error Handling and Debugging

std::format throws std::format_error on invalid format strings (e.g., mismatched braces, invalid specifiers). Always catch exceptions in production code. Use try-catch blocks around format calls. For debugging, you can use std::vformat with a std::format_args to inspect arguments. Also, consider using compile-time checks with constexpr format strings (C++20 allows constexpr std::format).

Example: Catching format errors.

#include <format>
#include <iostream>

int main() {
    try {
        std::string s = std::format("Missing brace: {0:", 42);
    } catch (const std::format_error& e) {
        std::cerr << "Format error: " << e.what() << '\n';
    }

    // Compile-time check (C++20)
    constexpr auto msg = std::format("Hello {}!", "world");
    std::cout << msg << '\n';

    return 0;
}