Format String Syntax¶

Format Specification Mini-Language¶

“Format specifications” are used within replacement fields contained within a format string to define how individual values are presented (see Format String Syntax). Each formattable type may define how the format specification is to be interpreted.

Most built-in types implement the following options for format specifications, although some of the formatting options are only supported by the numeric types.

The general form of a standard format specifier is:

format_spec ::=  [[fill]align][sign]["#"]["0"][width]["." precision]["L"][type]
fill        ::=  <a character other than '{' or '}'>
align       ::=  "<" | ">" | "^"
sign        ::=  "+" | "-" | " "
width       ::=  integer | "{" [arg_id] "}"
precision   ::=  integer | "{" [arg_id] "}"
type        ::=  "a" | "A" | "b" | "B" | "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" |
                 "o" | "p" | "s" | "x" | "X"

The fill character can be any Unicode code point other than '{' or '}'. The presence of a fill character is signaled by the character following it, which must be one of the alignment options. If the second character of format_spec is not a valid alignment option, then it is assumed that both the fill character and the alignment option are absent.

The meaning of the various alignment options is as follows:

Note that unless a minimum field width is defined, the field width will always be the same size as the data to fill it, so that the alignment option has no meaning in this case.

The sign option is only valid for number types, and can be one of the following:

The '#' option causes the “alternate form” to be used for the conversion. The alternate form is defined differently for different types. This option is only valid for integer and floating-point types. For integers, when binary, octal, or hexadecimal output is used, this option adds the prefix respective "0b" ("0B"), "0", or "0x" ("0X") to the output value. Whether the prefix is lower-case or upper-case is determined by the case of the type specifier, for example, the prefix "0x" is used for the type 'x' and "0X" is used for 'X'. For floating-point numbers the alternate form causes the result of the conversion to always contain a decimal-point character, even if no digits follow it. Normally, a decimal-point character appears in the result of these conversions only if a digit follows it. In addition, for 'g' and 'G' conversions, trailing zeros are not removed from the result.

width is a decimal integer defining the minimum field width. If not specified, then the field width will be determined by the content.

Preceding the width field by a zero ('0') character enables sign-aware zero-padding for numeric types. It forces the padding to be placed after the sign or base (if any) but before the digits. This is used for printing fields in the form ‘+000000120’. This option is only valid for numeric types and it has no effect on formatting of infinity and NaN.

The precision is a decimal number indicating how many digits should be displayed after the decimal point for a floating-point value formatted with 'f' and 'F', or before and after the decimal point for a floating-point value formatted with 'g' or 'G'. For non-number types the field indicates the maximum field size - in other words, how many characters will be used from the field content. The precision is not allowed for integer, character, Boolean, and pointer values. Note that a C string must be null-terminated even if precision is specified.

The 'L' option uses the current locale setting to insert the appropriate number separator characters. This option is only valid for numeric types.

Finally, the type determines how the data should be presented.

The available string presentation types are:

The available character presentation types are:

The available integer presentation types are:

Integer presentation types can also be used with character and Boolean values. Boolean values are formatted using textual representation, either true or false, if the presentation type is not specified.

The available presentation types for floating-point values are:

The available presentation types for pointers are:

Chrono Format Specifications¶

Format specifications for chrono types and std::tm have the following syntax:

chrono_format_spec ::=  [[fill]align][width]["." precision][chrono_specs]
chrono_specs       ::=  [chrono_specs] conversion_spec | chrono_specs literal_char
conversion_spec    ::=  "%" [modifier] chrono_type
literal_char       ::=  <a character other than '{', '}' or '%'>
modifier           ::=  "E" | "O"
chrono_type        ::=  "a" | "A" | "b" | "B" | "c" | "C" | "d" | "D" | "e" | "F" |
                        "g" | "G" | "h" | "H" | "I" | "j" | "m" | "M" | "n" | "p" |
                        "q" | "Q" | "r" | "R" | "S" | "t" | "T" | "u" | "U" | "V" |
                        "w" | "W" | "x" | "X" | "y" | "Y" | "z" | "Z" | "%"

Literal chars are copied unchanged to the output. Precision is valid only for std::chrono::duration types with a floating-point representation type.

The available presentation types (chrono_type) for chrono durations and time points are:

Specifiers that have a calendaric component such as 'd' (the day of month) are valid only for std::tm and not durations or time points.

Range Format Specifications¶

Format specifications for range types have the following syntax:

range_format_spec ::=  [":" [underlying_spec]]

The underlying_spec is parsed based on the formatter of the range’s reference type.

By default, a range of characters or strings is printed escaped and quoted. But if any underlying_spec is provided (even if it is empty), then the characters or strings are printed according to the provided specification.

Examples:

fmt::format("{}", std::vector{10, 20, 30});
// Result: [10, 20, 30]
fmt::format("{::#x}", std::vector{10, 20, 30});
// Result: [0xa, 0x14, 0x13]
fmt::format("{}", vector{'h', 'e', 'l', 'l', 'o'});
// Result: ['h', 'e', 'l', 'l', 'o']
fmt::format("{::}", vector{'h', 'e', 'l', 'l', 'o'});
// Result: [h, e, l, l, o]
fmt::format("{::d}", vector{'h', 'e', 'l', 'l', 'o'});
// Result: [104, 101, 108, 108, 111]

Format Examples¶

This section contains examples of the format syntax and comparison with the printf formatting.

In most of the cases the syntax is similar to the printf formatting, with the addition of the {} and with : used instead of %. For example, "%03.2f" can be translated to "{:03.2f}".

The new format syntax also supports new and different options, shown in the following examples.

Accessing arguments by position:

fmt::format("{0}, {1}, {2}", 'a', 'b', 'c');
// Result: "a, b, c"
fmt::format("{}, {}, {}", 'a', 'b', 'c');
// Result: "a, b, c"
fmt::format("{2}, {1}, {0}", 'a', 'b', 'c');
// Result: "c, b, a"
fmt::format("{0}{1}{0}", "abra", "cad");  // arguments' indices can be repeated
// Result: "abracadabra"

Aligning the text and specifying a width:

fmt::format("{:<30}", "left aligned");
// Result: "left aligned                  "
fmt::format("{:>30}", "right aligned");
// Result: "                 right aligned"
fmt::format("{:^30}", "centered");
// Result: "           centered           "
fmt::format("{:*^30}", "centered");  // use '*' as a fill char
// Result: "***********centered***********"

Dynamic width:

fmt::format("{:<{}}", "left aligned", 30);
// Result: "left aligned                  "

Dynamic precision:

fmt::format("{:.{}f}", 3.14, 1);
// Result: "3.1"

Replacing %+f, %-f, and % f and specifying a sign:

fmt::format("{:+f}; {:+f}", 3.14, -3.14);  // show it always
// Result: "+3.140000; -3.140000"
fmt::format("{: f}; {: f}", 3.14, -3.14);  // show a space for positive numbers
// Result: " 3.140000; -3.140000"
fmt::format("{:-f}; {:-f}", 3.14, -3.14);  // show only the minus -- same as '{:f}; {:f}'
// Result: "3.140000; -3.140000"

Replacing %x and %o and converting the value to different bases:

fmt::format("int: {0:d};  hex: {0:x};  oct: {0:o}; bin: {0:b}", 42);
// Result: "int: 42;  hex: 2a;  oct: 52; bin: 101010"
// with 0x or 0 or 0b as prefix:
fmt::format("int: {0:d};  hex: {0:#x};  oct: {0:#o};  bin: {0:#b}", 42);
// Result: "int: 42;  hex: 0x2a;  oct: 052;  bin: 0b101010"

Padded hex byte with prefix and always prints both hex characters:

fmt::format("{:#04x}", 0);
// Result: "0x00"

Box drawing using Unicode fill:

fmt::print(
  "┌{0:─^{2}}┐\n"
  "│{1: ^{2}}│\n"
  "└{0:─^{2}}┘\n", "", "Hello, world!", 20);

prints:

┌────────────────────┐
│   Hello, world!    │
└────────────────────┘

Using type-specific formatting:

#include <fmt/chrono.h>

auto t = 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

Using the comma as a thousands separator:

#include <fmt/format.h>

auto s = fmt::format(std::locale("en_US.UTF-8"), "{:L}", 1234567890);
// s == "1,234,567,890"