opening-bracket_ = STATICALLY-WIDEN("["); basic_string_view closing-bracket_ = STATICALLY-WIDEN("]"); public: constexpr void set_separator(basic_string_view sep) noexcept; constexpr void set_brackets(basic_string_view opening, basic_string_view closing) noexcept; constexpr formatter& underlying() noexcept { return underlying_; } constexpr const formatter& underlying() const noexcept { return underlying_; } template constexpr typename ParseContext::iterator parse(ParseContext& ctx); template requires formattable, charT> && same_as>, T> typename FormatContext::iterator format(R&& r, FormatContext& ctx) const; }; }">

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

28 Text processing library [text]

28.5 Formatting [format]

28.5.7 Formatting of ranges [format.range]

28.5.7.2 Class template range_formatter [format.range.formatter]

namespace std { template<class T, class charT = char> requires same_as<remove_cvref_t<T>, T> && formattable<T, charT> class range_formatter { formatter<T, charT> underlying_; basic_string_view<charT> separator_ = STATICALLY-WIDEN<charT>(", "); basic_string_view<charT> opening-bracket_ = STATICALLY-WIDEN<charT>("["); basic_string_view<charT> closing-bracket_ = STATICALLY-WIDEN<charT>("]"); public: constexpr void set_separator(basic_string_view<charT> sep) noexcept;constexpr void set_brackets(basic_string_view<charT> opening, basic_string_view<charT> closing) noexcept;constexpr formatter<T, charT>& underlying() noexcept { return underlying_; } constexpr const formatter<T, charT>& underlying() const noexcept { return underlying_; } template<class ParseContext> constexpr typename ParseContext::iterator parse(ParseContext& ctx);template<ranges::input_range R, class FormatContext> requires formattable<ranges::range_reference_t<R>, charT> && same_as<remove_cvref_t<ranges::range_reference_t<R>>, T> typename FormatContext::iterator format(R&& r, FormatContext& ctx) const;};}

The class template range_formatter is a utility for implementing formatter specializations for range types.

range_formatter interprets _format-spec_as a range-format-spec.

The syntax of format specifications is as follows:

range-format-spec :
range-fill-and-align width n range-type range-underlying-spec

range-fill-and-align :
range-fill align

range-fill :
any character other than { or } or :

range-underlying-spec :
: format-spec

For range_formatter<T, charT>, the _format-spec_in a range-underlying-spec, if any, is interpreted by formatter<T, charT>.

The n option causes the range to be formatted without the opening and closing brackets.

[Note 1:

This is equivalent to invoking set_brackets({}, {}).

— _end note_]

The range-type specifier changes the way a range is formatted, with certain options only valid with certain argument types.

The meaning of the various type options is as specified in Table 113.

Table 113 — Meaning of range-type options [tab:formatter.range.type]

🔗Option Requirements Meaning
🔗m T shall be either a specialization of pair or a specialization of tuplesuch that tuple_size_v<T> is 2. Indicates that the opening bracket should be "{", the closing bracket should be "}", the separator should be ", ", and each range element should be formatted as ifm were specified for its tuple-type. [Note 2: If the n option is provided in addition to the m option, both the opening and closing brackets are still empty. — _end note_]
🔗s T shall be charT. Indicates that the range should be formatted as a string.
🔗?s T shall be charT. Indicates that the range should be formatted as an escaped string ([format.string.escaped]).

If the range-type is s or ?s, then there shall be no n option and no range-underlying-spec.

constexpr void set_separator(basic_string_view<charT> sep) noexcept;

Effects: Equivalent to: separator_ = sep;

constexpr void set_brackets(basic_string_view<charT> opening, basic_string_view<charT> closing) noexcept;

Effects: Equivalent to:opening-bracket_ = opening;closing-bracket_ = closing;

template<class ParseContext> constexpr typename ParseContext::iterator parse(ParseContext& ctx);

Effects: Parses the format specifiers as a range-format-spec and stores the parsed specifiers in *this.

Calls underlying_.parse(ctx) to parse_format-spec_ in range-format-spec or, if the latter is not present, an empty format-spec.

The values of_opening-bracket__, closing-bracket_, and _separator__are modified if and only if required by the range-type or the n option, if present.

If:

  • the range-type is neither s nor ?s,
  • underlying_.set_debug_format() is a valid expression, and
  • there is no range-underlying-spec,

then calls underlying_.set_debug_format().

Returns: An iterator past the end of the range-format-spec.

template<ranges::[input_range](range.refinements#concept:input%5Frange "25.4.5 Other range refinements [range.refinements]") R, class FormatContext> requires [formattable](format.formattable#concept:formattable "28.5.6.3 Concept formattable [format.formattable]")<ranges::range_reference_t<R>, charT> && [same_as](concept.same#concept:same%5Fas "18.4.2 Concept same_­as [concept.same]")<remove_cvref_t<ranges::range_reference_t<R>>, T> typename FormatContext::iterator format(R&& r, FormatContext& ctx) const;

Effects: Writes the following into ctx.out(), adjusted according to the range-format-spec:

  • If the range-type was s, then as if by formatting basic_string<charT>(from_range, r).
  • Otherwise, if the range-type was ?s, then as if by formatting basic_string<charT>(from_range, r)as an escaped string ([format.string.escaped]).
  • Otherwise,
    • opening-bracket_,
    • for each element e of the range r:
      * the result of writing e via underlying_ and
      * separator_, unless e is the last element of r, and
    • closing-bracket_.

Returns: An iterator past the end of the output range.