[format.range] - C++20 → C++23

Files changed (1) hide show

tmp/tmpaj8sr_uq/{from.md → to.md} +415 -0

tmp/tmpaj8sr_uq/{from.md → to.md} RENAMED Viewed

	@@ -0,0 +1,415 @@

+### Formatting of ranges <a id="format.range">[[format.range]]</a>
+#### Variable template `format_kind` <a id="format.range.fmtkind">[[format.range.fmtkind]]</a>
+``` cpp
+template<ranges::input_range R>
+    requires same_as<R, remove_cvref_t<R>>
+  constexpr range_format format_kind<R> = see below;
+```
+A program that instantiates the primary template of `format_kind` is
+ill-formed.
+For a type `R`, `format_kind<R>` is defined as follows:
+- 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*]
+- Otherwise, if the *qualified-id* `R::key_type` is valid and denotes a
+  type:
+  - 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`.
+  - Otherwise, `format_kind<R>` is `range_format::set`.
+- Otherwise, `format_kind<R>` is `range_format::sequence`.
+*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`.
+#### Class template `range_formatter` <a id="format.range.formatter">[[format.range.formatter]]</a>
+``` cpp
+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;
+  };
+}
+```
+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:
+``` bnf
+range-format-spec
+    range-fill-and-alignₒₚₜ widthₒₚₜ 'n'ₒₚₜ range-typeₒₚₜ range-underlying-specₒₚₜ
+```
+``` bnf
+range-fill-and-align
+    range-fillₒₚₜ align
+```
+``` bnf
+range-fill
+    any character other than '{' or '}' or ':'
+```
+``` bnf
+range-type
+    'm'
+    's'
+    '?s'
+```
+``` bnf
+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 *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]].
+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 [[formatter.range.type]].
+**Table: Meaning of range-type options** <a id="formatter.range.type">[formatter.range.type]</a>
+| 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. *If the `n` option is provided in addition to the `m` option, both the opening and closing brackets are still empty.* |
+| % `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*.
+``` cpp
+constexpr void set_separator(basic_string_view<charT> sep) noexcept;
+```
+*Effects:* Equivalent to: *`separator_`*` = sep;`
+``` cpp
+constexpr void set_brackets(basic_string_view<charT> opening,
+                            basic_string_view<charT> closing) noexcept;
+```
+*Effects:* Equivalent to:
+``` cpp
+opening-bracket_ = opening;
+closing-bracket_ = closing;
+```
+``` cpp
+template<class ParseContext>
+  constexpr typename ParseContext::iterator
+    parse(ParseContext& ctx);
+```
+*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:
+- 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*.
+``` cpp
+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;
+```
+*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.
+#### Class template *`range-default-formatter`* <a id="format.range.fmtdef">[[format.range.fmtdef]]</a>
+``` cpp
+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;
+  };
+}
+```
+``` cpp
+constexpr void set_separator(basic_string_view<charT> sep) noexcept;
+```
+*Effects:* Equivalent to: *`underlying_`*`.set_separator(sep);`
+``` cpp
+constexpr void set_brackets(basic_string_view<charT> opening,
+                            basic_string_view<charT> closing) noexcept;
+```
+*Effects:* Equivalent to:
+*`underlying_`*`.set_brackets(opening, closing);`
+``` cpp
+template<class ParseContext>
+  constexpr typename ParseContext::iterator
+    parse(ParseContext& ctx);
+```
+*Effects:* Equivalent to: `return `*`underlying_`*`.parse(ctx);`
+``` cpp
+template<class FormatContext>
+  typename FormatContext::iterator
+    format(maybe-const-r& elems, FormatContext& ctx) const;
+```
+*Effects:* Equivalent to: `return `*`underlying_`*`.format(elems, ctx);`
+#### Specialization of *`range-default-formatter`* for maps <a id="format.range.fmtmap">[[format.range.fmtmap]]</a>
+``` cpp
+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;
+  };
+}
+```
+``` cpp
+constexpr range-default-formatter();
+```
+*Mandates:* Either:
+- *element-type* is a specialization of `pair`, or
+- *element-type* is a specialization of `tuple` and
+  `tuple_size_v<`*`element-type`*`> == 2`.
+*Effects:* Equivalent to:
+``` cpp
+underlying_.set_brackets(STATICALLY-WIDEN<charT>("{"), STATICALLY-WIDEN<charT>("}"));
+underlying_.underlying().set_brackets({}, {});
+underlying_.underlying().set_separator(STATICALLY-WIDEN<charT>(": "));
+```
+``` cpp
+template<class ParseContext>
+  constexpr typename ParseContext::iterator
+    parse(ParseContext& ctx);
+```
+*Effects:* Equivalent to: `return `*`underlying_`*`.parse(ctx);`
+``` cpp
+template<class FormatContext>
+  typename FormatContext::iterator
+    format(maybe-const-map& r, FormatContext& ctx) const;
+```
+*Effects:* Equivalent to: `return `*`underlying_`*`.format(r, ctx);`
+#### Specialization of *`range-default-formatter`* for sets <a id="format.range.fmtset">[[format.range.fmtset]]</a>
+``` cpp
+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;
+  };
+}
+```
+``` cpp
+constexpr range-default-formatter();
+```
+*Effects:* Equivalent to:
+``` cpp
+underlying_.set_brackets(STATICALLY-WIDEN<charT>("{"), STATICALLY-WIDEN<charT>("}"));
+```
+``` cpp
+template<class ParseContext>
+  constexpr typename ParseContext::iterator
+    parse(ParseContext& ctx);
+```
+*Effects:* Equivalent to: `return `*`underlying_`*`.parse(ctx);`
+``` cpp
+template<class FormatContext>
+  typename FormatContext::iterator
+    format(maybe-const-set& r, FormatContext& ctx) const;
+```
+*Effects:* Equivalent to: `return `*`underlying_`*`.format(r, ctx);`
+#### Specialization of *`range-default-formatter`* for strings <a id="format.range.fmtstr">[[format.range.fmtstr]]</a>
+``` cpp
+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;
+  };
+}
+```
+*Mandates:* `same_as<remove_cvref_t<range_reference_t<R>>, charT>` is
+`true`.
+``` cpp
+template<class ParseContext>
+  constexpr typename ParseContext::iterator
+    parse(ParseContext& ctx);
+```
+*Effects:* Equivalent to:
+``` cpp
+auto i = underlying_.parse(ctx);
+if constexpr (K == range_format::debug_string) {
+  underlying_.set_debug_format();
+}
+return i;
+```
+``` cpp
+template<class FormatContext>
+  typename FormatContext::iterator
+    format(see below& r, FormatContext& ctx) const;
+```
+The type of `r` is `const R&` if `ranges::input_range<const R>` is
+`true` and `R&` otherwise.
+*Effects:* Let *`s`* be a `basic_string<charT>` such that
+`ranges::equal(`*`s`*`, r)` is `true`. Equivalent to:
+`return `*`underlying_`*`.format(`*`s`*`, ctx);`

Diff to HTML by rtfpessoa