22 General utilities library [utilities]

22.14 Formatting [format]

22.14.7 Formatting of ranges [format.range]

22.14.7.1 Variable template format_kind [format.range.fmtkind]

🔗
template<ranges::input_range R> requires same_as<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<R> is defined as follows:
  • (2.1)
    If same_as<remove_cvref_t<ranges​::​range_reference_t<R>>, R> is true, format_kind<R> 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<R>>.
      If either U is a specialization of pair or U is a specialization of tuple and tuple_size_v<U> == 2, format_kind<R> is range_format​::​map.
    • (2.2.2)
      Otherwise, format_kind<R> is range_format​::​set.
  • (2.3)
    Otherwise, format_kind<R> 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.

22.14.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_; // exposition only basic_string_view<charT> separator_ = STATICALLY-WIDEN<charT>(", "); // exposition only basic_string_view<charT> opening-bracket_ = STATICALLY-WIDEN<charT>("["); // exposition only basic_string_view<charT> closing-bracket_ = STATICALLY-WIDEN<charT>("]"); // exposition only 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; }; }
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-align width n range-type range-underlying-spec
range-fill-and-align:
range-fill 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 76.
Table 76: 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<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 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 specifier as a range-format-spec and stores the parsed specifiers in *this.
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:
  • (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 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;
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<charT>(from_range, r).
  • (11.2)
    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]).
  • (11.3)
    Otherwise,
12
#
Returns: An iterator past the end of the output range.

22.14.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 only private: 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 only 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; template<class ParseContext> constexpr typename ParseContext::iterator parse(ParseContext& ctx); template<class FormatContext> typename 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);

22.14.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 only using element-type = // exposition only remove_cvref_t<ranges::range_reference_t<maybe-const-map>>; range_formatter<element-type, charT> underlying_; // exposition only public: constexpr range-default-formatter(); template<class ParseContext> constexpr typename ParseContext::iterator parse(ParseContext& ctx); template<class FormatContext> typename 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 and tuple_size_v<element-type> == 2.
2
#
Effects: Equivalent to: underlying_.set_brackets(STATICALLY-WIDEN<charT>("{"), STATICALLY-WIDEN<charT>("}")); underlying_.underlying().set_brackets({}, {}); underlying_.underlying().set_separator(STATICALLY-WIDEN<charT>(": "));
🔗
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);

22.14.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 only public: constexpr range-default-formatter(); template<class ParseContext> constexpr typename ParseContext::iterator parse(ParseContext& ctx); template<class FormatContext> typename FormatContext::iterator format(maybe-const-set& r, FormatContext& ctx) const; }; }
🔗
constexpr range-default-formatter();
1
#
Effects: Equivalent to: underlying_.set_brackets(STATICALLY-WIDEN<charT>("{"), STATICALLY-WIDEN<charT>("}"));
🔗
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);

22.14.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>, charT> underlying_; // exposition only public: template<class ParseContext> constexpr typename ParseContext::iterator parse(ParseContext& ctx); template<class FormatContext> typename FormatContext::iterator format(see below& str, FormatContext& ctx) const; }; }
1
#
Mandates: same_as<remove_cvref_t<range_reference_t<R>>, 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<const R> is true and R& otherwise.
4
#
Effects: Let s be a basic_string<charT> such that ranges​::​equal(s, r) is true.
Equivalent to: return underlying_.format(s, ctx);