For basic types and string types, the format specification is based on theformat specification in Python.

The syntax of format specifications is:

Thesign,# and0 options are only valid when an integer or floating-point presentation type is used.

[edit]Fill and align

fill-and-align is an optionalfill character (which can be any character other than{ or}), followed by one of thealign options<,>,^.

If no fill character is specified, it defaults to the space character. For a format specification in a Unicode encoding, the fill character must correspond to a single Unicode scalar value.

The meaning ofalign options is as follows:

• <: Forces the formatted argument to be aligned to the start of the available space by insertingn fill characters after the formatted argument. This is the default when a non-integer non-floating-point presentation type is used.
• >: Forces the formatted argument to be aligned to the end of the available space by insertingn fill characters before the formatted argument. This is the default when an integer or floating-point presentation type is used.
• ^: Forces the formatted argument to be centered within the available space by inserting⌊

  n

  2

  ⌋ characters before and⌈

  n

  2

  ⌉ characters after the formatted argument.

In each case,n is the difference of the minimum field width (specified bywidth) and theestimated width of the formatted argument, or 0 if the difference is less than 0.

#include <cassert>#include <format> int main(){char c=120;assert(std::format("{:6}",42)=="    42");assert(std::format("{:6}",'x')=="x     ");assert(std::format("{:*<6}",'x')=="x*****");assert(std::format("{:*>6}",'x')=="*****x");assert(std::format("{:*^6}",'x')=="**x***");assert(std::format("{:6d}", c)=="   120");assert(std::format("{:6}",true)=="true  ");}

[edit]Sign, #, and 0

Thesign option can be one of following:

• +: Indicates that a sign should be used for both non-negative and negative numbers. The+ sign is inserted before the output value for non-negative numbers.
• -: Indicates that a sign should be used for negative numbers only (this is the default behavior).
• space: Indicates that a leading space should be used for non-negative numbers, and a minus sign for negative numbers.

Negative zero is treated as a negative number.

Thesign option applies to floating-point infinity and NaN.

#include <cassert>#include <format>#include <limits> int main(){double inf=std::numeric_limits<double>::infinity();double nan=std::numeric_limits<double>::quiet_NaN();assert(std::format("{0:},{0:+},{0:-},{0: }",1)=="1,+1,1, 1");assert(std::format("{0:},{0:+},{0:-},{0: }",-1)=="-1,-1,-1,-1");assert(std::format("{0:},{0:+},{0:-},{0: }", inf)=="inf,+inf,inf, inf");assert(std::format("{0:},{0:+},{0:-},{0: }", nan)=="nan,+nan,nan, nan");}

The# option causes thealternate form to be used for the conversion.

• For integral types, when binary, octal, or hexadecimal presentation type is used, the alternate form inserts the prefix (0b,0, or0x) into the output value after the sign character (possibly space) if there is one, or add it before the output value otherwise.
• For floating-point types, the alternate form causes the result of the conversion of finite values 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, forg andG conversions, trailing zeros are not removed from the result.

The0 option pads the field with leading zeros (following any indication of sign or base) to the field width, except when applied to an infinity or NaN. If the0 character and analign option both appear, the0 character is ignored.

#include <cassert>#include <format> int main(){char c=120;assert(std::format("{:+06d}", c)=="+00120");assert(std::format("{:#06x}",0xa)=="0x000a");assert(std::format("{:<06}",-42)=="-42   ");// 0 is ignored because of '<'}

[edit]Width and precision

width is either a positive decimal number, or a nested replacement field ({} or{n}). If present, it specifies the minimum field width.

precision is a dot (.) followed by either a non-negative decimal number or a nested replacement field. This field indicates the precision or maximum field size. It can only be used with floating-point and string types.

• For floating-point types, this field specifies the formatting precision.
• For string types, it provides an upper bound for the estimated width (seebelow) of the prefix of the string to be copied to the output. For a string in a Unicode encoding, the text to be copied to the output is the longest prefix of whole extended grapheme clusters whose estimated width is no greater than the precision.

If a nested replacement field is used forwidth orprecision, and the corresponding argument is not ofintegral type(until C++23)standard signed or unsigned integer type(since C++23), or is negative, an exception of typestd::format_error is thrown.

float pi=3.14f;assert(std::format("{:10f}", pi)=="  3.140000");// width = 10assert(std::format("{:{}f}", pi,10)=="  3.140000");// width = 10assert(std::format("{:.5f}", pi)=="3.14000");// precision = 5assert(std::format("{:.{}f}", pi,5)=="3.14000");// precision = 5assert(std::format("{:10.5f}", pi)=="   3.14000");// width = 10, precision = 5assert(std::format("{:{}.{}f}", pi,10,5)=="   3.14000");// width = 10, precision = 5 auto b1=std::format("{:{}f}", pi,10.0);// throws: width is not of integral typeauto b2=std::format("{:{}f}", pi,-10);// throws: width is negativeauto b3=std::format("{:.{}f}", pi,5.0);// throws: precision is not of integral type

The width of a string is defined as the estimated number of column positions appropriate for displaying it in a terminal.

For the purpose of width computation, a string is assumed to be in an implementation-defined encoding. The method of width computation is unspecified, but for a string in a Unicode encoding, implementation should estimate the width of the string as the sum of estimated widths of the first code points in itsextended grapheme clusters. The estimated width is 2 for the following code points, and is 1 otherwise:

• Any code point whose Unicode propertyEast_Asian_Width has value Fullwidth (F) or Wide (W)
• U+4DC0 - U+4DFF (Yijing Hexagram Symbols)
• U+1F300 – U+1F5FF (Miscellaneous Symbols and Pictographs)
• U+1F900 – U+1F9FF (Supplemental Symbols and Pictographs)

#include <cassert>#include <format> int main(){assert(std::format("{:.^5s}","🐱")==".🐱..");assert(std::format("{:.5s}","🐱🐱🐱")=="🐱🐱");assert(std::format("{:.<5.5s}","🐱🐱🐱")=="🐱🐱.");}

[edit]L (locale-specific formatting)

TheL option causes the locale-specific form to be used. This option is only valid for arithmetic types.

• For integral types, the locale-specific form inserts the appropriate digit group separator characters according to the context's locale.
• For floating-point types, the locale-specific form inserts the appropriate digit group and radix separator characters according to the context's locale.
• For the textual representation ofbool, the locale-specific form uses the appropriate string as if obtained withstd::numpunct::truename orstd::numpunct::falsename.

[edit]Type

Thetype option determines how the data should be presented.

The available string presentation types are:

• none,s: Copies the string to the output.

The available integer presentation types for integral types other thanchar,wchar_t, andbool are:

• b: Binary format. Produces the output as if by callingstd::to_chars(first, last, value,2). The base prefix is0b.
• B: same asb, except that the base prefix is0B.
• c: Copies the characterstatic_cast<CharT>(value) to the output, whereCharT is the character type of the format string. Throwsstd::format_error if value is not in the range of representable values forCharT.
• d: Decimal format. Produces the output as if by callingstd::to_chars(first, last, value).
• o: Octal format. Produces the output as if by callingstd::to_chars(first, last, value,8). The base prefix is0 if the corresponding argument value is non-zero and is empty otherwise.
• x: Hex format. Produces the output as if by callingstd::to_chars(first, last, value,16). The base prefix is0x.
• X: same asx, except that it uses uppercase letters for digits above 9 and the base prefix is0X.
• none: same asd.

The availablechar andwchar_t presentation types are:

• none,c: Copies the character to the output.
• b,B,d,o,x,X: Uses integer presentation types with the valuestatic_cast<unsignedchar>(value) orstatic_cast<std::make_unsigned_t<wchar_t>>(value) respectively.

The availablebool presentation types are:

• none,s: Copies textual representation (true orfalse, or the locale-specific form) to the output.
• b,B,d,o,x,X: Uses integer presentation types with the valuestatic_cast<unsignedchar>(value).

The available floating-point presentation types are:

• a: Ifprecision is specified, produces the output as if by callingstd::to_chars(first, last, value, std::chars_format::hex, precision) whereprecision is the specified precision; otherwise, the output is produced as if by callingstd::to_chars(first, last, value, std::chars_format::hex).
• A: same asa, except that it uses uppercase letters for digits above 9 and usesP to indicate the exponent.
• e: Produces the output as if by callingstd::to_chars(first, last, value, std::chars_format::scientific, precision) whereprecision is the specified precision, or 6 if precision is not specified.
• E: same ase, except that it usesE to indicate the exponent.
• f,F: Produces the output as if by callingstd::to_chars(first, last, value, std::chars_format::fixed, precision) whereprecision is the specified precision, or 6 if precision is not specified.
• g: Produces the output as if by callingstd::to_chars(first, last, value, std::chars_format::general, precision) whereprecision is the specified precision, or 6 if precision is not specified.
• G: same asg, except that it usesE to indicate the exponent.
• none: Ifprecision is specified, produces the output as if by callingstd::to_chars(first, last, value, std::chars_format::general, precision) whereprecision is the specified precision; otherwise, the output is produced as if by callingstd::to_chars(first, last, value).

For lower-case presentation types, infinity and NaN are formatted asinf andnan, respectively.For upper-case presentation types, infinity and NaN are formatted asINF andNAN, respectively.

The available pointer presentation types (also used forstd::nullptr_t) are:

• none,p: Ifstd::uintptr_t is defined, produces the output as if by callingstd::to_chars(first, last,reinterpret_cast<std::uintptr_t>(value),16) with the prefix0x added to the output; otherwise, the output is implementation-defined.

#include <print> int main(){std::println("[{:?}]","h\tllo");// prints: ["h\tllo"]std::println("[{:?}]","Спасибо, Виктор ♥!");// prints: ["Спасибо, Виктор ♥!"]std::println("[{:?}] [{:?}]",'\'','"');// prints: ['\'', '"'] // The following examples assume use of the UTF-8 encodingstd::println("[{:?}]",std::string("\0\n\t\x02\x1b",9));// prints: ["\u{0} \n \t \u{2} \u{1b}"]std::println("[{:?}]","\xc3\x28");// invalid UTF-8// prints: ["\x{c3}("]std::println("[{:?}]","\u0301");// prints: ["\u{301}"]std::println("[{:?}]","\\\u0301");// prints: ["\\\u{301}"]std::println("[{:?}]","e\u0301\u0323");// prints: ["ẹ́"]}

[edit]Notes

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

[edit]Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

• In other languages

• Español
• 日本語
• Русский
• 中文