std::formatter<pair-or-tuple>
<format>
struct formatter</*pair-or-tuple*/<Ts...>, CharT>;
The template specialization of std::formatter for the std::pair and std::tuple allows users to convert a pair or a tuple to its textual representation as a collection of elements using formatting functions.
The exposition-only name /*pair-or-tuple*/ denotes either class template std::pair or std::tuple .
This specialization meets the Formatter requirements if (std::formattable <const Ts, CharT> && ...) is true. It always meets the BasicFormatter requirements.
Contents
[edit] Format specification
The syntax of tuple-format-spec is:
The tuple-fill-and-align is interpreted the same way as a fill-and-align except that the fill in tuple-fill-and-align is any character other than {
, }
, or :
.
The width is described in standard format width specification.
The tuple-type changes the way a tuple is formatted, with certain options only valid with certain argument types.
The available tuple presentation types are:
-
m
: Indicates that both opening and closing brackets should be "" while the separator should be ": ".
- If
m
is chosen as the tuple-type, the program is ill-formed unless sizeof...(Ts) == 2 is true.
- If
-
n
: Indicates that separator, opening and closing brackets should be "".
[edit] Member objects
underlying_
(private)
tuple of underlying formatters of type std::tuple <std::formatter <std::remove_cvref_t <Ts>, CharT>...>(exposition-only member object*)
separator_
(private)
a string representing the separator of the tuple formatted result (defaults to ", ")(exposition-only member object*)
opening-bracket_
(private)
a string representing the opening bracket of the tuple formatted result (defaults to "(")(exposition-only member object*)
closing-bracket_
(private)
a string representing the closing bracket of the tuple formatted result (defaults to ")")(exposition-only member object*)
[edit] Member functions
(public member function)
(public member function)
(public member function)
(public member function)
std::formatter<pair-or-tuple>::set_separator
Assigns sep to separator_
.
std::formatter<pair-or-tuple>::set_brackets
std::basic_string_view <CharT> closing ) noexcept;
Assigns opening and closing to opening-bracket_
and closing-bracket_
, respectively.
std::formatter<pair-or-tuple>::parse
constexpr auto parse( ParseContext& ctx ) -> ParseContext::iterator;
Parses the format specifiers as a tuple-format-spec and stores the parsed specifiers in the current object.
If tuple-type or the n
option is present, the values of opening-bracket
, closing-bracket
, and separator
are modified as required.
For each element e in underlying_
, calls e.parse(ctx) to parse an empty format-spec and, if e.set_debug_format() is a valid expression, calls e.set_debug_format().
Returns an iterator past the end of the tuple-format-spec.
std::formatter<pair-or-tuple>::format
FormatContext::iterator
/*maybe-const-pair-or-tuple*/ denotes:
- const /*pair-or-tuple*/, if (std::formattable <const Ts, CharT> && ...) is true,
- /*pair-or-tuple*/ otherwise.
Writes the following into ctx.out() as specified by tuple-format-spec, in order:
-
opening-bracket_
, - for each index I in
[
0,
sizeof...(Ts))
:
- if I != 0,
separator_
, - the result of writing std::get<I>(elems) via std::get<I>(
underlying_
), and
- if I != 0,
-
closing-bracket_
.
Returns an iterator past the end of the output range.
[edit] Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR | Applied to | Behavior as published | Correct behavior |
---|---|---|---|
LWG 3892 | C++23 | the formatting of nested tuples was incorrect | corrected |