std::range_formatter
<format>
requires std::same_as <std::remove_cvref_t <T>, T> && std::formattable <T, CharT>
std::range_formatter is a helper class template for implementing range std::formatter specializations.
Contents
[edit] Range format specification
The syntax of range-format-spec is:
n(optional) range-type (optional) range-underlying-spec (optional)
The range-fill-and-align is interpreted the same way as a fill-and-align except that the fill in range-fill-and-align is any character other than {, }, or :.
The width is described in standard format width specification.
The n option causes the range to be formatted without the opening and closing brackets.
assert (std::format ("{}", views::iota (1, 5)) == "[1, 2, 3, 4]"); assert (std::format ("{:n}", views::iota (1, 5)) == "1, 2, 3, 4");
The format-spec in a range-underlying-spec (its syntax is equivalent to : format-spec), if any, is interpreted by the range element formatter std::formatter<T, CharT>.
std::array ints{12, 10, 15, 14}; assert (std::format ("{}", ints) == "[12, 10, 15, 14]"); assert (std::format ("{::X}", ints) == "[C, A, F, E]"); assert (std::format ("{:n:_^4}", ints) == "_12_, _10_, _15_, _14_");
The range-type changes the way a range is formatted, with certain options only valid with certain argument types.
The available range presentation types are:
-
m: Indicates that the opening bracket should be "{", the closing bracket should be "}", the separator should be ", ", and each range element should be formatted as ifmwere specified for its tuple-type (in tuple-format-spec).
- If
mis chosen as the range-type, the program is ill-formed unlessTis either a specialization of:
- std::pair , or
- std::tuple such that std::tuple_size_v <T> == 2 is true.
- If
std::array char_pairs { std::pair {'A', 5}, std::pair {'B', 10}, std::pair {'C', 12} }; assert (std::format ("{}", char_pairs) == "[('A', 5), ('B', 10), ('C', 12)]"); assert (std::format ("{:m}", char_pairs) == "{'A': 5, 'B': 10, 'C': 12}");
-
s: Indicates that the range should be formatted as a string. -
?s: Indicates that the range should be formatted as an escaped string.
- If
sor?sis chosen as the range-type, bothnoption and range-underlying-spec should not be included in the format specifier, and - the program is ill-formed unless
TisCharT.
- If
std::array star{'S', 'T', 'A', 'R'}; assert (std::format ("{}", star) == "['S', 'T', 'A', 'R']"); assert (std::format ("{:s}", star) == "STAR"); assert (std::format ("{:?s}", star) == "\"STAR\"");
[edit] Data members
underlying_ (private)
the underlying formatter for elements(exposition-only member object*)
separator_ (private)
a string representing the separator of the range formatted result. The default separator is ", ".(exposition-only member object*)
opening-bracket_ (private)
a string representing the opening bracket of the range formatted result. The default opening bracket is "[".(exposition-only member object*)
closing-bracket_ (private)
a string representing the closing bracket of the range formatted result. The default closing bracket is "]".(exposition-only member object*)
[edit] Member functions
(public member function)
(public member function)
(public member function)
(public member function)
(public member function)
std::range_formatter::set_separator
Assigns sep to separator_.
std::range_formatter::set_brackets
std::basic_string_view <CharT> closing ) noexcept;
Assigns opening and closing to opening-bracket_ and closing-bracket_, respectively.
std::range_formatter::underlying
Returns underlying_ (the underlying formatter).
std::range_formatter::parse
constexpr auto parse( ParseContext& ctx ) -> ParseContext::iterator;
Parses the format specifiers as a range-format-spec and stores the parsed specifiers in the current object.
Calls underlying_.parse(ctx) to parse format-spec in range-format-spec or, if the latter is not present, an empty format-spec.
If range-type or the n option is present, the values of opening-bracket_, closing-bracket_, and separator_ are modified as required.
It calls underlying_.set_debug_format() if:
- the range-type is neither
snor?s, -
underlying_.set_debug_format() is a valid expression, and - there is no range-underlying-spec.
Returns an iterator past the end of the range-format-spec.
std::range_formatter::format
requires std::formattable <ranges::range_reference_t <R>, CharT> &&
std::same_as <std::remove_cvref_t <ranges::range_reference_t <R>>, T>
If the range-type was either s or ?s, it writes the formatted std::basic_string <CharT>(std::from_range, r) as a string or an escaped string, respectively, into ctx.out().
Otherwise, it writes the following into ctx.out() as specified by range-format-spec, in order:
-
opening-bracket_, - for each formattable element e of the range r:
- the result of writing e via
underlying_, and -
separator_, unless e is the last element of r, and
- the result of writing e via
-
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 ranges was incorrect | corrected |