cppdraft_translate/cppdraft/format/range.md

[format.range]

28 Text processing library [text]

28.5 Formatting [format]

28.5.7 Formatting of ranges [format.range]

28.5.7.1 Variable template format_kind [format.range.fmtkind]

🔗

template<ranges::[input_range](range.refinements#concept:input_range "25.4.6 Other range refinements [range.refinements]") R> requires [same_as](concept.same#concept:same_as "18.4.2 Concept same_­as [concept.same]")<R, remove_cvref_t<R>> constexpr range_format format_kind<R> = see below;

1

#

A program that instantiates the primary template of format_kind is ill-formed.

2

#

For a type R, format_kind is defined as follows:

• (2.1)

  If same_as<remove_cvref_t<ranges​::​range_reference_t>, R> is true,format_kind is range_format​::​disabled. [Note 1: This prevents constraint recursion for ranges whose reference type is the same range type. For example,std​::​filesystem​::​path is a range of std​::​filesystem​::​path. — end note]

• (2.2)

  Otherwise, if the qualified-id R​::​key_type is valid and denotes a type:

  • (2.2.1)

    If the qualified-id R​::​mapped_type is valid and denotes a type, let U be remove_cvref_t<ranges​::​range_reference_t>. If either U is a specialization of pair orU is a specialization of tuple andtuple_size_v == 2,format_kind is range_format​::​map.

  • (2.2.2)

    Otherwise, format_kind is range_format​::​set.

• (2.3)

  Otherwise, format_kind is range_format​::​sequence.

3

#

Remarks: Pursuant to [namespace.std], users may specialize format_kind for cv-unqualified program-defined types that model ranges​::​input_range.

Such specializations shall be usable in constant expressions ([expr.const]) and have type const range_format.

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> && formattable<T, charT>class range_formatter { formatter<T, charT> underlying_; // exposition only basic_string_view separator_ = STATICALLY-WIDEN(", "); // exposition only basic_string_view opening-bracket_ = STATICALLY-WIDEN("["); // exposition only basic_string_view closing-bracket_ = STATICALLY-WIDEN("]"); // exposition onlypublic:constexpr void set_separator(basic_string_view sep) noexcept; constexpr void set_brackets(basic_string_view opening, basic_string_view closing) noexcept; constexpr formatter<T, charT>& underlying() noexcept { return underlying_; }constexpr const formatter<T, charT>& underlying() const noexcept { return underlying_; }templateconstexpr typename ParseContext::iterator parse(ParseContext& ctx); template<ranges::input_range R, class FormatContext>requires formattable<ranges::range_reference_t, charT> &&same_as<remove_cvref_t<ranges::range_reference_t>, T>typename FormatContext::iterator format(R&& r, FormatContext& ctx) const; };}

1

#

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

2

#

range_formatter interprets format-spec as a range-format-spec.

The syntax of format specifications is as follows:

range-format-spec :
range-fill-and-alignopt widthopt nopt range-typeopt range-underlying-specopt

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

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

range-type :
m
s
?s

range-underlying-spec :

format-spec

3

#

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

4

#

The range-fill-and-align is interpreted the same way as a fill-and-align ([format.string.std]).

The productions align and width are described in [format.string].

5

#

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]

6

#

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 115.

Table 115 — 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 tuple such that tuple_size_v 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 if m 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;

7

#

Effects: Equivalent to: separator_ = sep;

🔗

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

8

#

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

🔗

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

9

#

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

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

The values ofopening-bracket_, closing-bracket_, and separator_ are modified if and only if required by the range-type or the n option, if present.

If:

• (9.1)

the range-type is neither s nor ?s,

• (9.2)

underlying_.set_debug_format() is a valid expression, and

• (9.3)

there is no range-underlying-spec,

then calls underlying_.set_debug_format().

10

#

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

🔗

template<ranges::[input_range](range.refinements#concept:input_range "25.4.6 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_as "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;

11

#

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

• (11.1)

  If the range-type was s, then as if by formatting basic_string(from_range, r).

• (11.2)

  Otherwise, if the range-type was ?s, then as if by formatting basic_string(from_range, r) as an escaped string ([format.string.escaped]).

• (11.3)

  Otherwise,

  • (11.3.1)

opening-bracket_,

• (11.3.2)

for each element e of the range r: + (11.3.2.1) the result of writing e via underlying_ and

+
      [(11.3.2.2)](#formatter-11.3.2.2)

separator_, unless e is the last element of r, and

• (11.3.3)

closing-bracket_.

12

#

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

28.5.7.3 Class template range-default-formatter [format.range.fmtdef]

🔗

namespace std {template<ranges::input_range R, class charT>struct range-default-formatter<range_format::sequence, R, charT> { // exposition onlyprivate:using maybe-const-r = fmt-maybe-const<R, charT>; // exposition only range_formatter<remove_cvref_t<ranges::range_reference_t<maybe-const-r>>, charT> underlying_; // exposition onlypublic:constexpr void set_separator(basic_string_view sep) noexcept; constexpr void set_brackets(basic_string_view opening, basic_string_view closing) noexcept; templateconstexpr typename ParseContext::iterator parse(ParseContext& ctx); templatetypename FormatContext::iterator format(maybe-const-r& elems, FormatContext& ctx) const; };}

🔗

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

1

#

Effects: Equivalent to: underlying_.set_separator(sep);

🔗

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

2

#

Effects: Equivalent to: underlying_.set_brackets(opening, closing);

🔗

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

3

#

Effects: Equivalent to: return underlying_.parse(ctx);

🔗

template<class FormatContext> typename FormatContext::iterator format(maybe-const-r& elems, FormatContext& ctx) const;

4

#

Effects: Equivalent to: return underlying_.format(elems, ctx);

28.5.7.4 Specialization of range-default-formatter for maps [format.range.fmtmap]

🔗

namespace std {template<ranges::input_range R, class charT>struct range-default-formatter<range_format::map, R, charT> {private:using maybe-const-map = fmt-maybe-const<R, charT>; // exposition onlyusing element-type = // exposition only remove_cvref_t<ranges::range_reference_t<maybe-const-map>>; range_formatter<element-type, charT> underlying_; // exposition onlypublic:constexpr range-default-formatter(); templateconstexpr typename ParseContext::iterator parse(ParseContext& ctx); templatetypename FormatContext::iterator format(maybe-const-map& r, FormatContext& ctx) const; };}

🔗

constexpr range-default-formatter();

1

#

Mandates: Either:

• (1.1)

element-type is a specialization of pair, or

• (1.2)

element-type is a specialization of tuple andtuple_size_v<element-type> == 2.

2

#

Effects: Equivalent to:underlying_.set_brackets(STATICALLY-WIDEN("{"), STATICALLY-WIDEN("}"));underlying_.underlying().set_brackets({}, {});underlying_.underlying().set_separator(STATICALLY-WIDEN(": "));

🔗

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

3

#

Effects: Equivalent to: return underlying_.parse(ctx);

🔗

template<class FormatContext> typename FormatContext::iterator format(maybe-const-map& r, FormatContext& ctx) const;

4

#

Effects: Equivalent to: return underlying_.format(r, ctx);

28.5.7.5 Specialization of range-default-formatter for sets [format.range.fmtset]

🔗

namespace std {template<ranges::input_range R, class charT>struct range-default-formatter<range_format::set, R, charT> {private:using maybe-const-set = fmt-maybe-const<R, charT>; // exposition only range_formatter<remove_cvref_t<ranges::range_reference_t<maybe-const-set>>, charT> underlying_; // exposition onlypublic:constexpr range-default-formatter(); templateconstexpr typename ParseContext::iterator parse(ParseContext& ctx); templatetypename FormatContext::iterator format(maybe-const-set& r, FormatContext& ctx) const; };}

🔗

constexpr range-default-formatter();

1

#

Effects: Equivalent to:underlying_.set_brackets(STATICALLY-WIDEN("{"), STATICALLY-WIDEN("}"));

🔗

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

2

#

Effects: Equivalent to: return underlying_.parse(ctx);

🔗

template<class FormatContext> typename FormatContext::iterator format(maybe-const-set& r, FormatContext& ctx) const;

3

#

Effects: Equivalent to: return underlying_.format(r, ctx);

28.5.7.6 Specialization of range-default-formatter for strings [format.range.fmtstr]

🔗

namespace std {template<range_format K, ranges::input_range R, class charT>requires (K == range_format::string || K == range_format::debug_string)struct range-default-formatter<K, R, charT> {private: formatter<basic_string, charT> underlying_; // exposition onlypublic:templateconstexpr typename ParseContext::iterator parse(ParseContext& ctx); templatetypename FormatContext::iterator format(see below& str, FormatContext& ctx) const; };}

1

#

Mandates: same_as<remove_cvref_t<range_reference_t>, charT> is true.

🔗

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

2

#

Effects: Equivalent to:auto i = underlying_.parse(ctx);if constexpr (K == range_format::debug_string) {underlying_.set_debug_format();}return i;

🔗

template<class FormatContext> typename FormatContext::iterator format(see below& r, FormatContext& ctx) const;

3

#

The type of r is const R& if ranges​::​input_range is true andR& otherwise.

4

#

Effects: Let s be a basic_string such thatranges​::​equal(s, r) is true.

Equivalent to: return underlying_.format(s, ctx);