View source for cpp/utility/format/tuple formatter

You do not have permission to edit this page, for the following reasons:

The action you have requested is limited to users in one of the groups: Users, Administrators.

Due to recent vandalism, editing of this page is temporarily disabled for new users.If you want to suggest a change, please leave a message on the suggestions page for new users instead (don't be surprised if that page appears vandalized!).

You can view and copy the source of this page.

{{cpp/title|formatter{{small|<''pair-or-tuple''>}}}}
{{cpp/utility/format/navbar}}

{{dcl begin}}
{{dcl header|format}}
{{dcl|since=c++23|1=
template< class CharT, std::formattable<CharT>... Ts >
struct formatter</*pair-or-tuple*/<Ts...>, CharT>;
}}
{{dcl end}}

The template specialization of {{lc|std::formatter}} for the {{lc|std::pair}} and {{lc|std::tuple}} allows users to convert a pair or a tuple to its textual representation as a collection of elements using [[cpp/utility/format|formatting functions]].

The exposition-only name {{c/core|/*pair-or-tuple*/}} denotes either class template {{lc|std::pair}} or {{lc|std::tuple}}.

This specialization meets the {{named req|Formatter}} requirements if {{c|(std::formattable<const Ts, CharT> && ...)}} is {{c|true}}. It always meets the {{named req|BasicFormatter}} requirements.

===Format specification===
The syntax of {{spar|tuple-format-spec}} is:
{{sdsc begin}}
{{sdsc|
{{spar optional|tuple-fill-and-align}} {{spar optional|width}} {{spar optional|tuple-type}}
}}
{{sdsc end}}

The {{spar|tuple-fill-and-align}} is interpreted the same way as a {{spar|fill-and-align}} except that the {{spar|fill}} in {{spar|tuple-fill-and-align}} is any character other than {{ttb|{}}, {{ttb|}<!---->}}, or {{ttb|:}}. 

The {{spar|width}} is described in {{rlp|spec#Width and precision|standard format width specification}}.

The {{spar|tuple-type}} changes the way a tuple is formatted, with certain options only valid with certain argument types. 

The available tuple presentation types are:
* {{ttb|m}}: Indicates that both opening and closing brackets should be {{c|""}} while the separator should be {{c|": "}}.

:* If {{ttb|m}} is chosen as the {{spar|tuple-type}}, the program is ill-formed unless {{c|1=sizeof...(Ts) == 2}} is {{c|true}}.

* {{ttb|n}}: Indicates that separator, opening and closing brackets should be {{c|""}}.

===Member objects===
{{dsc begin}}
{{dsc hitem|Member name|Definition}}
{{dsc expos mem obj|private=yes|underlying_|tuple of underlying formatters of type {{c/core|std::tuple<std::formatter<std::remove_cvref_t<Ts>, CharT>...>}}}}
{{dsc expos mem obj|private=yes|separator_|a string representing the separator of the tuple formatted result (defaults to {{c|", "}})}}
{{dsc expos mem obj|private=yes|opening-bracket_|a string representing the opening bracket of the tuple formatted result (defaults to {{c|"("}})}}
{{dsc expos mem obj|private=yes|closing-bracket_|a string representing the closing bracket of the tuple formatted result (defaults to {{c|")"}})}}
{{dsc end}}

===Member functions===
{{dsc begin}}
{{dsc mem fun|set_separator|nolink=true|sets a specified separator for the tuple formatted result}}
{{dsc mem fun|set_brackets|nolink=true|sets a specified opening and closing brackets for the tuple formatted result}}
{{dsc mem fun|parse|nolink=true|parses the format specifier as specified by {{spar|tuple-format-spec}}}}
{{dsc mem fun|format|nolink=true|writes the tuple formatted output as specified by {{spar|tuple-format-spec}}}}
{{dsc end}}

{{member|1={{small|std::formatter<''pair-or-tuple''>::}}set_separator|2=
{{dcl begin}}
{{dcl|1=
constexpr void set_separator( std::basic_string_view<CharT> sep ) noexcept;
}}
{{dcl end}}

Assigns {{c|sep}} to {{tti|separator_}}.
}}

{{member|1={{small|std::formatter<''pair-or-tuple''>::}}set_brackets|2=
{{dcl begin}}
{{dcl|1=
constexpr void set_brackets( std::basic_string_view<CharT> opening,
                             std::basic_string_view<CharT> closing ) noexcept;
}}
{{dcl end}}

Assigns {{c|opening}} and {{c|closing}} to {{tti|opening-bracket_}} and {{tti|closing-bracket_}}, respectively.
}}

{{member|1={{small|std::formatter<''pair-or-tuple''>::}}parse|2=
{{dcl begin}}
{{dcl|1=
template< class ParseContext >
constexpr auto parse( ParseContext& ctx ) -> ParseContext::iterator;
}}
{{dcl end}}

Parses the format specifiers as a {{spar|tuple-format-spec}} and stores the parsed specifiers in the current object.

If {{spar|tuple-type}} or the {{ttb|n}} option is present, the values of {{tti|opening-bracket}}, {{tti|closing-bracket}}, and {{tti|separator}} are modified as required.

For each element {{c|e}} in {{box|{{tti|underlying_}}}}, calls {{c|e.parse(ctx)}} to parse an empty {{spar|format-spec}} and, if {{c|e.set_debug_format()}} is a valid expression, calls {{c|e.set_debug_format()}}.

Returns an iterator past the end of the {{spar|tuple-format-spec}}.
}}

{{member|1={{small|std::formatter<''pair-or-tuple''>::}}format|2=
{{dcl begin}}
{{dcl|1=
template< class FormatContext >
FormatContext::iterator
format( /*maybe-const-pair-or-tuple*/<Ts...>& elems, FormatContext& ctx ) const;
}}
{{dcl end}}

{{c/core|/*maybe-const-pair-or-tuple*/}} denotes:
* {{c/core|const /*pair-or-tuple*/}}, if {{c|(std::formattable<const Ts, CharT> && ...)}} is {{c|true}},
* {{c/core|/*pair-or-tuple*/}} otherwise.

Writes the following into {{c|ctx.out()}} as specified by {{spar|tuple-format-spec}}, in order:
* {{box|{{tti|opening-bracket_}}}},
* for each index {{c|I}} in {{range|0|sizeof...(Ts)}}:
:* if {{c|1=I != 0}}, {{box|{{tti|separator_}}}},
:* the result of writing {{c|std::get<I>(elems)}} via {{box|{{c/core|std::get<I>(}}{{tti|underlying_}}{{c/core|)}}}}, and
* {{box|{{tti|closing-bracket_}}}}.

Returns an iterator past the end of the output range.
}}

===Defect reports===
{{dr list begin}}
{{dr list item|wg=lwg|dr=3892|std=c++23|before=the formatting of nested tuples was incorrect|after=corrected}}
{{dr list end}}

{{langlinks|es|ja|ru|zh}}

===See also===
{{dsc begin}}
{{dsc inc|cpp/utility/format/dsc formatter}}
{{dsc end}}

Templates used on this page:

Template:box (view source)
Template:box/core (view source)
Template:c (view source) (protected)
Template:c/core (view source) (protected)
Template:cpp/navbar content (view source)
Template:cpp/navbar heading (view source)
Template:cpp/text/navbar content (view source)
Template:cpp/text/navbar heading (view source)
Template:cpp/title (view source) (protected)
Template:cpp/utility/format/dsc formatter (view source)
Template:cpp/utility/format/navbar (view source)
Template:cpp/utility/format/navbar content (view source)
Template:cpp/utility/format/navbar heading (view source)
Template:ctitle (view source) (protected)
Template:dcl (view source) (protected)
Template:dcl/std (view source) (semi-protected)
Template:dcl begin (view source) (protected)
Template:dcl end (view source) (protected)
Template:dcl header (view source) (protected)
Template:dcl list header/link (view source)
Template:dcl sep (view source) (protected)
Template:dr list begin (view source)
Template:dr list end (view source)
Template:dr list item (view source)
Template:dsc (view source) (protected)
Template:dsc begin (view source) (protected)
Template:dsc editlink (view source)
Template:dsc end (view source) (protected)
Template:dsc expos mem obj (view source)
Template:dsc guard (view source) (protected)
Template:dsc header/link (view source)
Template:dsc hitem (view source) (protected)
Template:dsc inc (view source) (protected)
Template:dsc mark mem (view source) (protected)
Template:dsc mem fun (view source) (protected)
Template:dsc member (view source) (protected)
Template:dsc small (view source)
Template:dsc tclass (view source) (protected)
Template:get lang (view source) (protected)
Template:get lang formal (view source)
Template:langlinks (view source) (protected)
Template:langlinks/one (view source) (protected)
Template:lc (view source) (protected)
Template:lines (view source) (protected)
Template:list guard (view source)
Template:ls (view source)
Template:ltt/core (view source) (protected)
Template:mark (view source) (protected)
Template:mark c++11 (

cppreference.com

Search

Namespaces

Variants

Views

Actions

View source for cpp/utility/format/tuple formatter