| Localization library | |||||||||||||||||||||||||
| Regular expressions library(C++11) | |||||||||||||||||||||||||
| Formatting library(C++20) | |||||||||||||||||||||||||
| Null-terminated sequence utilities | |||||||||||||||||||||||||
| Byte strings | |||||||||||||||||||||||||
| Multibyte strings | |||||||||||||||||||||||||
| Wide strings | |||||||||||||||||||||||||
| Primitive numeric conversions | |||||||||||||||||||||||||
| |||||||||||||||||||||||||
| Text encoding identifications | |||||||||||||||||||||||||
| |||||||||||||||||||||||||
| Standard format specification | ||||
| Formatting functions | ||||
(C++20) | ||||
(C++20) | ||||
(C++20) | ||||
(C++20) | ||||
(C++20) | ||||
(C++20) | ||||
| Format strings | ||||
(C++20)(C++20)(C++20) | ||||
(C++26) | ||||
| Formatting concepts | ||||
(C++23) | ||||
| Formatter | ||||
(C++20) | ||||
(C++23) | ||||
(C++23) | ||||
range_formatter (C++23) | ||||
(C++20)(C++20)(C++20) | ||||
(C++20)(C++20)(C++20) | ||||
(C++23) | ||||
(C++23) | ||||
| Formatting arguments | ||||
(C++20) | ||||
(C++20) | ||||
(C++20)(C++20)(C++20) | ||||
(C++20)(deprecated in C++26) | ||||
(C++20)(C++20) | ||||
| Format error | ||||
(C++20) |
Defined in header <format> | ||
template<class T,class CharT=char> requiresstd::same_as<std::remove_cvref_t<T>, T>&&std::formattable<T, CharT> | (since C++23) | |
std::range_formatter is a helper class template for implementing rangestd::formatter specializations.
Contents |
The syntax ofrange-format-spec is:
range-fill-and-align (optional)width (optional)n(optional)range-type (optional)range-underlying-spec (optional) | |||||||||
Therange-fill-and-align is interpreted the same way as afill-and-align except that thefill inrange-fill-and-align is any character other than{,}, or:.
Thewidth is described instandard format width specification.
Then 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");
Theformat-spec in arange-underlying-spec (its syntax is equivalent to:format-spec), if any, is interpreted by the range element formatterstd::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_");
Therange-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 ifm were specified for itstuple-type (intuple-format-spec).m is chosen as therange-type, the program is ill-formed unlessT is either a specialization of: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 anescaped string.s or?s is chosen as therange-type, bothn option andrange-underlying-spec should not be included in the format specifier, andT isCharT.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\"");
| Member name | Definition |
std::formatter<T, CharT>underlying_(private) | the underlying formatter for elements (exposition-only member object*) |
std::basic_string_view<CharT>separator_(private) | a string representing the separator of the range formatted result. The default separator is", ". (exposition-only member object*) |
std::basic_string_view<CharT>opening-bracket_(private) | a string representing the opening bracket of the range formatted result. The default opening bracket is"[". (exposition-only member object*) |
std::basic_string_view<CharT>closing-bracket_(private) | a string representing the closing bracket of the range formatted result. The default closing bracket is"]". (exposition-only member object*) |
set_separator | sets a specified separator for the range formatted result (public member function) |
set_brackets | sets a specified opening and closing brackets for the range formatted result (public member function) |
underlying | returns the underlying formatter (public member function) |
parse | parses the format specifier as specified byrange-format-spec (public member function) |
format | writes the range formatted output as specified byrange-format-spec (public member function) |
constexprvoid set_separator(std::basic_string_view<CharT> sep)noexcept; | ||
Assignssep toseparator_.
constexprvoid set_brackets(std::basic_string_view<CharT> opening, std::basic_string_view<CharT> closing)noexcept; | ||
Assignsopening andclosing toopening-bracket_ andclosing-bracket_, respectively.
constexprstd::formatter<T, CharT>& underlying(); | (1) | |
constexprconststd::formatter<T, CharT>& underlying()const; | (2) | |
Returnsunderlying_ (the underlying formatter).
template<class ParseContext> constexprauto parse( ParseContext& ctx)-> ParseContext::iterator; | ||
Parses the format specifiers as arange-format-spec and stores the parsed specifiers in the current object.
Callsunderlying_.parse(ctx) to parseformat-spec inrange-format-spec or, if the latter is not present, an emptyformat-spec.
Ifrange-type or then option is present, the values ofopening-bracket_,closing-bracket_, andseparator_ are modified as required.
It callsunderlying_.set_debug_format() if:
s nor?s,underlying_.set_debug_format() is a valid expression, andReturns an iterator past the end of therange-format-spec.
template<ranges::input_range R,class FormatContext> requiresstd::formattable<ranges::range_reference_t<R>, CharT>&& | ||
If therange-type was eithers or?s, it writes the formattedstd::basic_string<CharT>(std::from_range, r) as a string or an escaped string, respectively, intoctx.out().
Otherwise, it writes the following intoctx.out() as specified byrange-format-spec, in order:
opening-bracket_,underlying_, andseparator_, unlesse is the last element ofr, andclosing-bracket_.Returns an iterator past the end of the output range.
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 |
(C++20) | defines formatting rules for a given type (class template)[edit] |
