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
mis 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 |