5.6 KiB
[format.formatter.spec]
28 Text processing library [text]
28.5 Formatting [format]
28.5.6 Formatter [format.formatter]
28.5.6.4 Formatter specializations [format.formatter.spec]
The functions defined in [format.functions] use specializations of the class template formatter to format individual arguments.
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 ?.
Each header that declares the template formatter provides the following enabled specializations:
The debug-enabled specializationstemplate<> struct formatter<char, char>;template<> struct formatter<char, wchar_t>;template<> struct formatter<wchar_t, wchar_t>;
For each charT, the debug-enabled string type specializationstemplate<> 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>;templatestruct formatter<basic_string_view<charT, traits>, charT>;
For each charT, for each cv-unqualified arithmetic type ArithmeticT other thanchar,wchar_t,char8_t,char16_t, orchar32_t, a specializationtemplate<> struct formatter<ArithmeticT, charT>;
For each charT, the pointer type specializationstemplate<> struct formatter<nullptr_t, charT>;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].
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 = true;
[Note 1:
Specializations such as formatter<wchar_t, char> that would require implicit multibyte / wide string or character conversion are disabled.
â end note]
The header provides the following disabled specializations:
The string type specializationstemplate<> 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>;templatestruct formatter<basic_string_view<char, traits>, wchar_t>;
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.
If the library provides an explicit or partial specialization offormatter<T, charT>, that specialization is enabled and meets the Formatter requirements except as noted otherwise.
If F is a disabled specialization of formatter, these values are false:
is_default_constructible_v,
is_copy_constructible_v,
is_move_constructible_v,
is_copy_assignable_v, and
is_move_assignable_v.
An enabled specialization formatter<T, charT> meets theBasicFormatter requirements ([formatter.requirements]).
[Example 1: #include #include enum color { red, green, blue };const char* color_names[] = { "red", "green", "blue" };
template<> struct std::formatter : 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]