std::formatter(3)

NAME
std::formatter - std::formatter

Synopsis
   Defined in header <format>
   template<class T, class CharT = char> (since C++20)
   struct formatter;
   The enabled specializations of formatter define formatting rules for a given type.
   Enabled specializations meet the Formatter requirements. In particular, they define
   callables parse and format.
   For all types T and CharT for which no specialization std::formatter<T, CharT> is
   enabled, that specialization is a complete type and is disabled.
   Disabled specializations do not meet the Formatter requirements, and the following
   are all false:
     * std::is_default_constructible_v
     * std::is_copy_constructible_v
     * std::is_move_constructible_v
     * std::is_copy_assignable_v
     * std::is_move_assignable_v.
  Standard specializations for basic types and string types
   In the following list, CharT is either char or wchar_t, ArithmeticT is any
   cv-unqualified arithmetic type other than char, wchar_t, char8_t, char16_t, or
   char32_t.
   template<> struct formatter<char, char>;
   template<> struct formatter<char, wchar_t>;
   template<> struct formatter<wchar_t, wchar_t>;
   template<> struct formatter<CharT*, CharT>;
   template<> struct formatter<const CharT*, CharT>;
   template<std::size_t N> struct formatter<CharT[N], CharT>;
   template<std::size_t N> struct formatter<const CharT[N], CharT>;
   template<class Traits, class Alloc>
   struct formatter<std::basic_string<CharT, Traits, Alloc>, CharT>;
   template<class Traits>
   struct formatter<std::basic_string_view<CharT, Traits>, CharT>;
   template<> struct formatter<ArithmeticT, CharT>;
   template<> struct formatter<std::nullptr_t, CharT>;
   template<> struct formatter<void*, CharT>;
   template<> struct formatter<const void*, CharT>;
   Formatters for other pointers and pointers to members are disabled.
   Specializations such as std::formatter<wchar_t, char> and std::formatter<const
   char*, wchar_t> that would require encoding conversions are disabled.
    Standard format specification
   For basic types and string types, the format specification is based on the format
   specification in Python.
   The syntax of format specifications is:
   fill-and-align(optional) sign(optional) #(optional) 0(optional)
   width(optional) precision(optional) L(optional) type(optional)
   The sign, # and 0 options are only valid when an integer or floating-point
   presentation type is used.
      fill and align
   fill-and-align is an optional fill character (which can be any character other than
   { or }), followed by one of the align options <, >, ^. The meaning of align options
   is as follows:
     * <: Forces the field to be aligned to the start of the available space. This is
       the default when a non-integer non-floating-point presentation type is used.
     * >: Forces the field to be aligned to the end of the available space. This is the
       default when an integer or floating-point presentation type is used.
     * ^: Forces the field to be centered within the available space by inserting ⌊
       n
       2
       ⌋ characters before and ⌈
       n
       2
       ⌉ characters after the value, where n is the total number of fill characters
       to insert.
 char c = 120;
 auto s0 = std::format("{:6}", 42); // value of s0 is " 42"
 auto s1 = std::format("{:6}", 'x'); // value of s1 is "x "
 auto s2 = std::format("{:*<6}", 'x'); // value of s2 is "x*****"
 auto s3 = std::format("{:*>6}", 'x'); // value of s3 is "*****x"
 auto s4 = std::format("{:*^6}", 'x'); // value of s4 is "**x***"
 auto s5 = std::format("{:6d}", c); // value of s5 is " 120"
 auto s6 = std::format("{:6}", true); // value of s6 is "true "
      sign, #, and 0
   The sign 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.
   The sign option applies to floating-point infinity and NaN.
 double inf = std::numeric_limits<double>::infinity();
 double nan = std::numeric_limits<double>::quiet_NaN();
 auto s0 = std::format("{0:},{0:+},{0:-},{0: }", 1); // value of s0 is "1,+1,1, 1"
 auto s1 = std::format("{0:},{0:+},{0:-},{0: }", -1); // value of s1 is "-1,-1,-1,-1"
 auto s2 = std::format("{0:},{0:+},{0:-},{0: }", inf); // value of s2 is "inf,+inf,inf, inf"
 auto s3 = std::format("{0:},{0:+},{0:-},{0: }", nan); // value of s3 is "nan,+nan,nan, nan"
   The # option causes the alternate 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, or 0x) 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, for g and G conversions,
       trailing zeros are not removed from the result.
   The 0 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 the 0
   character and an align option both appear, the 0 character is ignored.
 char c = 120;
 auto s1 = std::format("{:+06d}", c); // value of s1 is "+00120"
 auto s2 = std::format("{:#06x}", 0xa); // value of s2 is "0x000a"
 auto s3 = std::format("{:<06}", -42); // value of s3 is "-42 "
                        // (0 is ignored because of < alignment)
      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 (see below) 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 for width or precision, and the corresponding
   argument is not of integral type, or is negative, or is zero for width, an exception
   of type std::format_error is thrown.
 float pi = 3.14f;
 auto s1 = std::format("{:10f}", pi); // s1 = " 3.140000" (width = 10)
 auto s2 = std::format("{:{}f}", pi, 10); // s2 = " 3.140000" (width = 10)
 auto s3 = std::format("{:.5f}", pi); // s3 = "3.14000" (precision = 5)
 auto s4 = std::format("{:.{}f}", pi, 5); // s4 = "3.14000" (precision = 5)
 auto s5 = std::format("{:10.5f}", pi); // s5 = " 3.14000"
                        // (width = 10, precision = 5)
 auto s6 = std::format("{:{}.{}f}", pi, 10, 5); // s6 = " 3.14000"
                        // (width = 10, precision = 5)
 auto b1 = std::format("{:{}f}", pi, 10.0); // throws: width is not of integral type
 auto b2 = std::format("{:{}f}", pi, -10); // throws: width is negative
 auto b3 = std::format("{:.{}f}", pi, 5.0); // throws: precision is not of integral type
   For string types, the width 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 a
   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 its extended
   grapheme clusters. The estimated width of a Unicode code point is 2 if the code
   point is within the following range, or 1 if it isn't:
     * U+1100 - U+115F
     * U+2329 - U+232A
     * U+2E80 - U+303E
     * U+3040 - U+A4CF
     * U+AC00 - U+D7A3
     * U+F900 - U+FAFF
     * U+FE10 - U+FE19
     * U+FE30 - U+FE6F
     * U+FF00 - U+FF60
     * U+FFE0 - U+FFE6
     * U+1F300 - U+1F64F
     * U+1F900 - U+1F9FF
     * U+20000 - U+2FFFD
     * U+30000 - U+3FFFD
 auto s1 = std::format("{:.^5s}", "🐱"); // s1 = ".🐱.."
 auto s2 = std::format("{:.5s}", "🐱🐱🐱"); // s2 = "🐱🐱"
 auto s3 = std::format("{:.<5.5s}", "🐱🐱🐱"); // s3 = "🐱🐱."
      L (locale-specific formatting)
   The L 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 of bool, the locale-specific form uses the
       appropriate string as if obtained with std::numpunct::truename or
       std::numpunct::falsename.
      type
   The type 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 than char,
   wchar_t, and bool are:
     * b: Binary format. Produces the output as if by calling std::to_chars(first,
       last, value, 2). The base prefix is 0b.
     * B: same as b, except that the base prefix is 0B.
     * c: Copies the character static_cast<CharT>(value) to the output, where CharT is
       the character type of the format string. Throws std::format_error if value is
       not in the range of representable values for CharT.
     * d: Decimal format. Produces the output as if by calling std::to_chars(first,
       last, value).
     * o: Octal format. Produces the output as if by calling std::to_chars(first, last,
       value, 8). The base prefix is 0 if the corresponding argument value is nonzero
       and is empty otherwise.
     * x: Hex format. Produces the output as if by calling std::to_chars(first, last,
       value, 16). The base prefix is 0x.
     * X: same as x, except that it uses uppercase letters for digits above 9 and the
       base prefix is 0X.
     * none: same as d.
   The available char and wchar_t presentation types are:
     * none, c: Copies the character to the output.
     * b, B, d, o, x, X: Uses integer presentation types.
   The available bool presentation types are:
     * none, s: Copies textual representation (true or false, or the locale-specific
       form) to the output.
     * b, B, c, d, o, x, X: Uses integer presentation types with the value
       static_cast<unsigned char>(value).
   The available floating-point presentation types are:
     * a: If precision is specified, produces the output as if by calling
       std::to_chars(first, last, value, std::chars_format::hex, precision) where
       precision is the specified precision; otherwise, the output is produced as if by
       calling std::to_chars(first, last, value, std::chars_format::hex).
     * A: same as a, except that it uses uppercase letters for digits above 9 and uses
       P to indicate the exponent.
     * e: Produces the output as if by calling std::to_chars(first, last, value,
       std::chars_format::scientific, precision) where precision is the specified
       precision, or 6 if precision is not specified.
     * E: same as e, except that it uses E to indicate the exponent.
     * f, F: Produces the output as if by calling std::to_chars(first, last, value,
       std::chars_format::fixed, precision) where precision is the specified precision,
       or 6 if precision is not specified.
     * g: Produces the output as if by calling std::to_chars(first, last, value,
       std::chars_format::general, precision) where precision is the specified
       precision, or 6 if precision is not specified.
     * G: same as g, except that it uses E to indicate the exponent.
     * none: If precision is specified, produces the output as if by calling
       std::to_chars(first, last, value, std::chars_format::general, precision) where
       precision is the specified precision; otherwise, the output is produced as if by
       calling std::to_chars(first, last, value).
   For lower-case presentation types, infinity and NaN are formatted as inf and nan,
   respectively. For upper-case presentation types, infinity and NaN are formatted as
   INF and NAN, respectively.
   The available pointer presentation types (also used for std::nullptr_t) are:
     * none, p: If std::uintptr_t is defined, produces the output as if by calling
       std::to_chars(first, last, reinterpret_cast<std::uintptr_t>(value), 16) with the
       prefix 0x added to the output; otherwise, the output is implementation-defined.

Standard specializations for library types
                        specialization of
   std::formatter<std::chrono::duration> std::formatter that formats a
   (C++20) duration according to the
                        provided format
                        (class template specialization)
                        specialization of
   std::formatter<std::chrono::sys_time> std::formatter that formats a
   (C++20) sys_time according to the
                        provided format
                        (class template specialization)
                        specialization of
   std::formatter<std::chrono::utc_time> std::formatter that formats a
   (C++20) utc_time according to the
                        provided format
                        (class template specialization)
                        specialization of
   std::formatter<std::chrono::tai_time> std::formatter that formats a
   (C++20) tai_time according to the
                        provided format
                        (class template specialization)
                        specialization of
   std::formatter<std::chrono::gps_time> std::formatter that formats a
   (C++20) gps_time according to the
                        provided format
                        (class template specialization)
                        specialization of
   std::formatter<std::chrono::file_time> std::formatter that formats a
   (C++20) file_time according to the
                        provided format
                        (class template specialization)
                        specialization of
   std::formatter<std::chrono::local_time> std::formatter that formats a
   (C++20) local_time according to the
                        provided format
                        (class template specialization)
                        specialization of
   std::formatter<std::chrono::day> std::formatter that formats a
   (C++20) day according to the provided
                        format
                        (class template specialization)
                        specialization of
   std::formatter<std::chrono::month> std::formatter that formats a
   (C++20) month according to the provided
                        format
                        (class template specialization)
                        specialization of
   std::formatter<std::chrono::year> std::formatter that formats a
   (C++20) year according to the provided
                        format
                        (class template specialization)
                        specialization of
   std::formatter<std::chrono::weekday> std::formatter that formats a
   (C++20) weekday according to the
                        provided format
                        (class template specialization)
                        specialization of
   std::formatter<std::chrono::weekday_indexed> std::formatter that formats a
   (C++20) weekday_indexed according to
                        the provided format
                        (class template specialization)
                        specialization of
   std::formatter<std::chrono::weekday_last> std::formatter that formats a
   (C++20) weekday_last according to the
                        provided format
                        (class template specialization)
                        specialization of
   std::formatter<std::chrono::month_day> std::formatter that formats a
   (C++20) month_day according to the
                        provided format
                        (class template specialization)
                        specialization of
   std::formatter<std::chrono::month_day_last> std::formatter that formats a
   (C++20) month_day_last according to the
                        provided format
                        (class template specialization)
                        specialization of
   std::formatter<std::chrono::month_weekday> std::formatter that formats a
   (C++20) month_weekday according to the
                        provided format
                        (class template specialization)
                        specialization of
   std::formatter<std::chrono::month_weekday_last> std::formatter that formats a
   (C++20) month_weekday_last according to
                        the provided format
                        (class template specialization)
                        specialization of
   std::formatter<std::chrono::year_month> std::formatter that formats a
   (C++20) year_month according to the
                        provided format
                        (class template specialization)
                        specialization of
   std::formatter<std::chrono::year_month_day> std::formatter that formats a
   (C++20) year_month_day according to the
                        provided format
                        (class template specialization)
                        specialization of
   std::formatter<std::chrono::year_month_day_last> std::formatter that formats a
   (C++20) year_month_day_last according
                        to the provided format
                        (class template specialization)
                        specialization of
   std::formatter<std::chrono::year_month_weekday> std::formatter that formats a
   (C++20) year_month_weekday according to
                        the provided format
                        (class template specialization)
                        specialization of
                        std::formatter that formats a
   std::formatter<std::chrono::year_month_weekday_last> year_month_weekday_last
   (C++20) according to the provided
                        format
                        (class template specialization)
                        specialization of
   std::formatter<std::chrono::hh_mm_ss> std::formatter that formats a
   (C++20) hh_mm_ss according to the
                        provided format
                        (class template specialization)
                        specialization of
   std::formatter<std::chrono::sys_info> std::formatter that formats a
   (C++20) sys_info according to the
                        provided format
                        (class template specialization)
                        specialization of
   std::formatter<std::chrono::local_info> std::formatter that formats a
   (C++20) local_info according to the
                        provided format
                        (class template specialization)
                        specialization of
   std::formatter<std::chrono::zoned_time> std::formatter that formats a
   (C++20) zoned_time according to the
                        provided format
                        (class template specialization)

Example
// Run this code
 #include <format>
 #include <iostream>
 // A wrapper for type T
 template<class T>
 struct Box {
     T value;
 };
 // The wrapper Box<T> can be formatted using the format specification of the wrapped value
 template<class T, class CharT>
 struct std::formatter<Box<T>, CharT> : std::formatter<T, CharT> {
     // parse() is inherited from the base class
     // Define format() by calling the base class implementation with the wrapped value
     template<class FormatContext>
     auto format(Box<T> t, FormatContext& fc) const {
         return std::formatter<T, CharT>::format(t.value, fc);
     }
 };
 int main() {
     Box<int> v = { 42 };
     std::cout << std::format("{:#x}", v);
 }

Output:
 0x2a

See also
   basic_format_context
   format_context formatting state, including all formatting arguments and the
   wformat_context output iterator
   (C++20) (class template)
   (C++20)
   (C++20)