28 Text processing library [text]

28.5 Formatting [format]

28.5.6 Formatter [format.formatter]

28.5.6.4 Formatter specializations [format.formatter.spec]

1
#
The functions defined in [format.functions] use specializations of the class template formatter to format individual arguments.
2
#
Let charT be either char or wchar_t.
Each specialization of formatter is either enabled or disabled, as described below.
A debug-enabled specialization of formatter additionally provides a public, constexpr, non-static member function set_debug_format() which modifies the state of the formatter to be as if the type of the std-format-spec parsed by the last call to parse were ?.
A constexpr-enabled specialization of formatter has its format member function declared constexpr.
Each header that declares the template formatter provides the following enabled specializations:
  • (2.1)
    The debug-enabled and constexpr-enabled specializations template<> struct formatter<char, char>; template<> struct formatter<char, wchar_t>; template<> struct formatter<wchar_t, wchar_t>;
  • (2.2)
    For each charT, the debug-enabled and constexpr-enabled string type specializations template<> struct formatter<charT*, charT>; template<> struct formatter<const charT*, charT>; template<size_t N> struct formatter<charT[N], charT>; template<class traits, class Allocator> struct formatter<basic_string<charT, traits, Allocator>, charT>; template<class traits> struct formatter<basic_string_view<charT, traits>, charT>;
  • (2.3)
    For each charT, for each IntegerT that is either a signed or unsigned integer type or bool, a constexpr-enabled specialization template<> struct formatter<IntegerT, charT>;
  • (2.4)
    For each charT, for each FloatingT that is a cv-unqualified floating-point type, a specialization template<> struct formatter<FloatingT, charT>;
  • (2.5)
    For each charT, the constexpr-enabled pointer type specialization template<> struct formatter<nullptr_t, charT>;
  • (2.6)
    For each charT, the pointer type specializations template<> struct formatter<void*, charT>; template<> struct formatter<const void*, charT>;
The parse member functions of these formatters interpret the format specification as a std-format-spec as described in [format.string.std].
3
#
Unless specified otherwise, for each type T for which a formatter specialization is provided by the library, each of the headers provides the following specialization: template<> inline constexpr bool enable_nonlocking_formatter_optimization<T> = true;
[Note 1: 
Specializations such as formatter<wchar_t, char> that would require implicit multibyte / wide string or character conversion are disabled.
— end note]
4
#
The header <format> provides the following disabled specializations:
  • (4.1)
    The string type specializations template<> struct formatter<char*, wchar_t>; template<> struct formatter<const char*, wchar_t>; template<size_t N> struct formatter<char[N], wchar_t>; template<class traits, class Allocator> struct formatter<basic_string<char, traits, Allocator>, wchar_t>; template<class traits> struct formatter<basic_string_view<char, traits>, wchar_t>;
5
#
For any types T and charT for which neither the library nor the user provides an explicit or partial specialization of the class template formatter, formatter<T, charT> is disabled.
6
#
If the library provides an explicit or partial specialization of formatter<T, charT>, that specialization is enabled and meets the Formatter requirements except as noted otherwise.
7
#
If F is a disabled specialization of formatter, these values are false:
  • (7.1)
    is_default_constructible_v<F>,
  • (7.2)
    is_copy_constructible_v<F>,
  • (7.3)
    is_move_constructible_v<F>,
  • (7.4)
    is_copy_assignable_v<F>, and
  • (7.5)
    is_move_assignable_v<F>.
8
#
An enabled specialization formatter<T, charT> meets the BasicFormatter requirements ([formatter.requirements]).
[Example 1: #include <format> #include <string> enum color { red, green, blue }; const char* color_names[] = { "red", "green", "blue" }; template<> struct std::formatter<color> : std::formatter<const char*> { auto format(color c, format_context& ctx) const { return formatter<const char*>::format(color_names[c], ctx); } }; struct err {}; std::string s0 = std::format("{}", 42); // OK, library-provided formatter std::string s1 = std::format("{}", L"foo"); // error: disabled formatter std::string s2 = std::format("{}", red); // OK, user-provided formatter std::string s3 = std::format("{}", err{}); // error: disabled formatter — end example]