std::format — Python-Style Formatting in C++

Why a new formatting library?

Before C++20, you had two choices for string formatting, each with a fatal flaw. C-style printf is concise and readable — the format string is clearly separated from its arguments — but it is not type-safe (passing a double for a %d specifier is undefined behavior) and cannot be extended to support your own types. The C++ stream approach (std::cout <<) is type-safe and extensible via operator<<, but the format string and arguments are interleaved, making it hard to read and nearly impossible to localize for different languages. std::format is the best of both worlds.

printf("x=%d y=%d\n", x, y);
// passing wrong type → UB

cout << "x=" << x
     << " y=" << y
     << endl;

println("x={} y={}", x, y);
// type-safe, readable, extensible

Basic usage: format, print, println

std::format(), defined in <format>, returns a formatted std::string. Its C++23 siblings std::print() and std::println() (in <print>) write directly to an output stream — by default stdout, the same destination as std::cout, but with better Unicode support and better performance. println appends a newline; print does not. When you can use C++23, prefer println over std::format + cout.

import std;   // or: #include <format> and #include <print>

int x { 42 };
double pi { 3.14159 };
std::string name { "Alice" };

// std::format returns a std::string
std::string s = std::format("x={} pi={} name={}", x, pi, name);
// s == "x=42 pi=3.14159 name=Alice"

// std::print / std::println (C++23) write to stdout directly
std::println("x={} pi={} name={}", x, pi, name);
// output: x=42 pi=3.14159 name=Alice

// Print to stderr
std::println(std::cerr, "Error: value {} is out of range", x);

Replacement fields and argument indices

Every {} in a format string is a replacement field. The full syntax for a replacement field is {[index][:specifier]}. When you omit the index, arguments are consumed left-to-right. When you specify an index (zero-based), you can reorder, repeat, or skip arguments — which is essential for internationalization, where different languages may use the same values in a different order. You cannot mix automatic and manual indexing in the same format string. Literal { and } characters are escaped by doubling them: {{ and }}.

int n { 42 };
std::string file { "data.txt" };

// Automatic indexing (left-to-right)
std::println("Read {} bytes from {}", n, file);
// → Read 42 bytes from data.txt

// Manual indexing — same result, arguments explicitly addressed
std::println("Read {0} bytes from {1}", n, file);

// Reordered for Chinese (argument order unchanged, format order swapped)
std::println("从{1}中读取{0}个字节。", n, file);
// → 从data.txt中读取42个字节。

// Repeat an argument
std::println("{0} × {0} = {1}", 7, 49);
// → 7 × 7 = 49

// Escape literal braces
std::println("Set notation: {{{}}}",  42);
// → Set notation: {42}

Format specifiers

After the colon inside a replacement field comes the format specifier, which controls precisely how the value is rendered. The general grammar is:

{ [index] : [[fill]align] [sign] [#] [0] [width] [.precision] [L] [type] }

All parts are optional and can be combined in any subset.

int i { 42 };
std::println("|{:5}|",    i);   // |   42|     (right-aligned, width 5)
std::println("|{:<7}|",   i);   // |42     |   (left-aligned, width 7)
std::println("|{:^7}|",   i);   // |  42   |   (center-aligned, width 7)
std::println("|{:_>7}|",  i);   // |_____42|   (fill with '_', right-align)
std::println("|{:_^10}|", i);   // |____42____|  (fill with '_', center)

// Dynamic width — taken from argument
int width { 10 };
std::println("|{:{}}|",   i, width);          // |        42|
std::println("|{1:{0}}|", width, i);          // |        42| (indexed)

// String with fill — useful for simple table borders
std::println("|{:=>16}|", "");   // |================|

int i { 42 };
std::println("|{:5}|",    i);   // |   42|   (default: no + sign)
std::println("|{:+5}|",   i);   // |  +42|   (always show sign)
std::println("|{:< 5}|",  i);   // |   42|   (space for positive)
std::println("|{:< 5}|", -i);   // |  -42|   (minus for negative)

int i { 42 };
std::println("|{:10d}|",  i);   // |        42|   decimal (default)
std::println("|{:10b}|",  i);   // |    101010|   binary
std::println("|{:#10b}|", i);   // |  0b101010|   binary with 0b prefix
std::println("|{:10X}|",  i);   // |        2A|   uppercase hex
std::println("|{:#10X}|", i);   // |      0X2A|   hex with 0X prefix

// String centering
std::string s { "ProCpp" };
std::println("|{:_^10}|", s);   // |__ProCpp__|

// Boolean
bool b { true };
std::println("{}", b);    // true   (default: string form)
std::println("{:d}", b);  // 1      (integer form)

double d { 3.1415 / 2.3 };
std::println("|{:12}|",    d);  // |     1.36587|   (default)
std::println("|{:12.2}|",  d);  // |         1.4|   (2 sig digits)
std::println("|{:12.2f}|", d);  // |        1.37|   (2 decimal places, fixed)
std::println("|{:12e}|",   d);  // |1.365870e+00|   (scientific)

// Dynamic precision
int width { 12 }, prec { 3 };
std::println("|{2:{0}.{1}f}|", width, prec, d);   // |       1.366|

int i { 42 };
std::println("|{:06d}|",   i);  // |000042|
std::println("|{:+06d}|",  i);  // |+00042|   (sign before zeros)
std::println("|{:#06X}|",  i);  // |0X002A|   (prefix, then zeros)

// Locale-specific (format only, not println)
float f { 1234.5f };
std::cout << std::format(std::locale{"nl"}, "{:Lg}\n", f);
// → 1.234,5  (Dutch locale: period as thousands sep, comma as decimal)

Formatting ranges (C++23)

C++23 allows formatting containers and ranges directly. A vector, array, pair, or any range can be passed as an argument to format()/println() without writing a loop. By default, sequences are surrounded by square brackets with comma-separated elements; pairs use parentheses. The full range specifier grammar adds control over surrounding brackets, per-element formatting, and string-like output.

std::vector values { 11, 22, 33 };

std::println("{}", values);        // [11, 22, 33]    (default)
std::println("{:n}", values);      // 11, 22, 33      (n = omit brackets)
std::println("{{{:n}}}", values);  // {11, 22, 33}    (custom brackets via escaped {})

// Range width/fill applies to the whole range output
std::println("{:*^16}", values);   // **[11, 22, 33]**
std::println("{:*^16n}", values);  // ***11, 22, 33***

// Per-element specifier — nested after ::
std::println("{::^6}", values);    // [  11  ,   22  ,   33  ]  (each element centered width 6)
std::println("{:n:*^6}", values);  // **11**, **22**, **33**     (n + per-element)

// Formatting pairs (default: parentheses, comma-separated)
std::pair p { 11, 22 };
std::println("{}", p);    // (11, 22)
std::println("{:n}", p);  // 11, 22
std::println("{:m}", p);  // 11: 22   (m = map-like key: value format)

// Formatting strings as ranges of characters
std::vector<char> chars { 'W','o','r','l','d','\t','!' };
std::println("{}", chars);    // ['W', 'o', 'r', 'l', 'd', '\t', '!']
std::println("{:s}", chars);  // World	!   (string form, no escaping)
std::println("{:?s}", chars); // "World\t!"  (escaped string form)

Escaped string/char output (C++23)

The ? type specifier formats strings and characters as they would appear in C++ source code — surrounded by quotes and with control characters escaped. This is primarily useful for debugging and logging, where you need to see invisible characters (tabs, newlines) literally.

std::println("|{:?}|", "Hello\tWorld!\n");  // |"Hello\tWorld!\n"|
std::println("|{:?}|", "\"quoted\"");         // |"\"quoted\""|
std::println("|{:?}|", '\t');                // |'\t'|
std::println("|{:?}|", ''');                // |'\''|

Custom type support

The formatting library is extensible: any type can be made formattable by specializing std::formatter<T> in the std namespace. The specialization needs two member functions: parse(), which reads the format specifier substring from the format string, and format(), which writes the formatted value to the output context. Once written, the specialization integrates seamlessly — your type works with all the standard specifiers you compose in the formatter, and supports nested format specs just like built-in types. The next lesson covers writing custom formatters in detail.

struct Point { int x, y; };

template <>
class std::formatter<Point>
{
public:
    constexpr auto parse(auto& context) {
        return context.begin();   // no custom specifiers for now
    }
    auto format(const Point& p, auto& ctx) const {
        return std::format_to(ctx.out(), "({}, {})", p.x, p.y);
    }
};

int main()
{
    Point pt { 3, 7 };
    std::println("Point: {}", pt);            // Point: (3, 7)
    std::println("Centered: {:^12}", pt);     // Centered:   (3, 7)
    std::vector<Point> pts { {1,2}, {3,4} };
    std::println("{}", pts);                  // [(1, 2), (3, 4)]
}

Specifier quick reference