[format.formatter.spec] (original) (raw)

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 formatteradditionally 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 formatterprovides 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>;template<class traits> struct formatter<basic_string_view<charT, traits>, charT>;
• For each charT, for each cv-unqualified arithmetic type ArithmeticTother 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<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_]

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>;template<class traits> struct 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<F>,
• is_copy_constructible_v<F>,
• is_move_constructible_v<F>,
• is_copy_assignable_v<F>, and
• is_move_assignable_v<F>.

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); std::string s1 = std::format("{}", L"foo"); std::string s2 = std::format("{}", red); std::string s3 = std::format("{}", err{}); — _end example_]