[format.arguments] - C++17 → C++20

Files changed (1) hide show

tmp/tmp9scplc6k/{from.md → to.md} +284 -0

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

	@@ -0,0 +1,284 @@

+### Arguments <a id="format.arguments">[[format.arguments]]</a>
+#### Class template `basic_format_arg` <a id="format.arg">[[format.arg]]</a>
+``` cpp
+namespace std {
+  template<class Context>
+  class basic_format_arg {
+  public:
+    class handle;
+  private:
+    using char_type = typename Context::char_type;                              // exposition only
+    variant<monostate, bool, char_type,
+            int, unsigned int, long long int, unsigned long long int,
+            float, double, long double,
+            const char_type*, basic_string_view<char_type>,
+            const void*, handle> value;                                         // exposition only
+    template<class T> explicit basic_format_arg(const T& v) noexcept;           // exposition only
+    explicit basic_format_arg(float n) noexcept;                                // exposition only
+    explicit basic_format_arg(double n) noexcept;                               // exposition only
+    explicit basic_format_arg(long double n) noexcept;                          // exposition only
+    explicit basic_format_arg(const char_type* s);                              // exposition only
+    template<class traits>
+      explicit basic_format_arg(
+        basic_string_view<char_type, traits> s) noexcept;                       // exposition only
+    template<class traits, class Allocator>
+      explicit basic_format_arg(
+        const basic_string<char_type, traits, Allocator>& s) noexcept;          // exposition only
+    explicit basic_format_arg(nullptr_t) noexcept;                              // exposition only
+    template<class T>
+      explicit basic_format_arg(const T* p) noexcept;                           // exposition only
+  public:
+    basic_format_arg() noexcept;
+    explicit operator bool() const noexcept;
+  };
+}
+```
+An instance of `basic_format_arg` provides access to a formatting
+argument for user-defined formatters.
+The behavior of a program that adds specializations of
+`basic_format_arg` is undefined.
+``` cpp
+basic_format_arg() noexcept;
+```
+*Ensures:* `!(*this)`.
+``` cpp
+template<class T> explicit basic_format_arg(const T& v) noexcept;
+```
+*Constraints:* The template specialization
+``` cpp
+typename Context::template formatter_type<T>
+```
+meets the requirements [[formatter.requirements]]. The extent to which
+an implementation determines that the specialization meets the
+requirements is unspecified, except that as a minimum the expression
+``` cpp
+typename Context::template formatter_type<T>()
+  .format(declval<const T&>(), declval<Context&>())
+```
+shall be well-formed when treated as an unevaluated operand.
+*Effects:*
+- if `T` is `bool` or `char_type`, initializes `value` with `v`;
+- otherwise, if `T` is `char` and `char_type` is `wchar_t`, initializes
+  `value` with `static_cast<wchar_t>(v)`;
+- otherwise, if `T` is a signed integer type [[basic.fundamental]] and
+  `sizeof(T) <= sizeof(int)`, initializes `value` with
+  `static_cast<int>(v)`;
+- otherwise, if `T` is an unsigned integer type and
+  `sizeof(T) <= sizeof(unsigned int)`, initializes `value` with
+  `static_cast<unsigned int>(v)`;
+- otherwise, if `T` is a signed integer type and
+  `sizeof(T) <= sizeof(long long int)`, initializes `value` with
+  `static_cast<long long int>(v)`;
+- otherwise, if `T` is an unsigned integer type and
+  `sizeof(T) <= sizeof(unsigned long long int)`, initializes `value`
+  with `static_cast<unsigned long long int>(v)`;
+- otherwise, initializes `value` with `handle(v)`.
+``` cpp
+explicit basic_format_arg(float n) noexcept;
+explicit basic_format_arg(double n) noexcept;
+explicit basic_format_arg(long double n) noexcept;
+```
+*Effects:* Initializes `value` with `n`.
+``` cpp
+explicit basic_format_arg(const char_type* s);
+```
+*Preconditions:* `s` points to a NTCTS [[defns.ntcts]].
+*Effects:* Initializes `value` with `s`.
+``` cpp
+template<class traits>
+  explicit basic_format_arg(basic_string_view<char_type, traits> s) noexcept;
+```
+*Effects:* Initializes `value` with `s`.
+``` cpp
+template<class traits, class Allocator>
+  explicit basic_format_arg(
+    const basic_string<char_type, traits, Allocator>& s) noexcept;
+```
+*Effects:* Initializes `value` with
+`basic_string_view<char_type>(s.data(), s.size())`.
+``` cpp
+explicit basic_format_arg(nullptr_t) noexcept;
+```
+*Effects:* Initializes `value` with `static_cast<const void*>(nullptr)`.
+``` cpp
+template<class T> explicit basic_format_arg(const T* p) noexcept;
+```
+*Constraints:* `is_void_v<T>` is `true`.
+*Effects:* Initializes `value` with `p`.
+[*Note 1*: Constructing `basic_format_arg` from a pointer to a member
+is ill-formed unless the user provides an enabled specialization of
+`formatter` for that pointer to member type. — *end note*]
+``` cpp
+explicit operator bool() const noexcept;
+```
+*Returns:* `!holds_alternative<monostate>(value)`.
+The class `handle` allows formatting an object of a user-defined type.
+``` cpp
+namespace std {
+  template<class Context>
+  class basic_format_arg<Context>::handle {
+    const void* ptr_;                                           // exposition only
+    void (*format_)(basic_format_parse_context<char_type>&,
+                    Context&, const void*);                     // exposition only
+    template<class T> explicit handle(const T& val) noexcept;   // exposition only
+    friend class basic_format_arg<Context>;                     // exposition only
+  public:
+    void format(basic_format_parse_context<char_type>&, Context& ctx) const;
+  };
+}
+```
+``` cpp
+template<class T> explicit handle(const T& val) noexcept;
+```
+*Effects:* Initializes `ptr_` with `addressof(val)` and `format_` with
+``` cpp
+[](basic_format_parse_context<char_type>& parse_ctx,
+   Context& format_ctx, const void* ptr) {
+  typename Context::template formatter_type<T> f;
+  parse_ctx.advance_to(f.parse(parse_ctx));
+  format_ctx.advance_to(f.format(*static_cast<const T*>(ptr), format_ctx));
+}
+```
+``` cpp
+void format(basic_format_parse_context<char_type>& parse_ctx, Context& format_ctx) const;
+```
+*Effects:* Equivalent to: `format_(parse_ctx, format_ctx, ptr_);`
+``` cpp
+template<class Visitor, class Context>
+  see below visit_format_arg(Visitor&& vis, basic_format_arg<Context> arg);
+```
+*Effects:* Equivalent to:
+`return visit(forward<Visitor>(vis), arg.value);`
+#### Class template *`format-arg-store`* <a id="format.arg.store">[[format.arg.store]]</a>
+``` cpp
+namespace std {
+  template<class Context, class... Args>
+  struct format-arg-store {      // exposition only
+    array<basic_format_arg<Context>, sizeof...(Args)> args;
+  };
+}
+```
+An instance of *`format-arg-store`* stores formatting arguments.
+``` cpp
+template<class Context = format_context, class... Args>
+  format-arg-store<Context, Args...> make_format_args(const Args&... args);
+```
+*Preconditions:* The type
+`typename Context::template formatter_type<``Tᵢ``>` meets the
+requirements [[formatter.requirements]] for each `Tᵢ` in `Args`.
+*Returns:* `{basic_format_arg<Context>(args)...}`.
+``` cpp
+template<class... Args>
+  format-arg-store<wformat_context, Args...> make_wformat_args(const Args&... args);
+```
+*Effects:* Equivalent to:
+`return make_format_args<wformat_context>(args...);`
+#### Class template `basic_format_args` <a id="format.args">[[format.args]]</a>
+``` cpp
+namespace std {
+  template<class Context>
+  class basic_format_args {
+    size_t size_;                               // exposition only
+    const basic_format_arg<Context>* data_;     // exposition only
+  public:
+    basic_format_args() noexcept;
+    template<class... Args>
+      basic_format_args(const format-arg-store<Context, Args...>& store) noexcept;
+    basic_format_arg<Context> get(size_t i) const noexcept;
+  };
+}
+```
+An instance of `basic_format_args` provides access to formatting
+arguments.
+``` cpp
+basic_format_args() noexcept;
+```
+*Effects:* Initializes `size_` with `0`.
+``` cpp
+template<class... Args>
+  basic_format_args(const format-arg-store<Context, Args...>& store) noexcept;
+```
+*Effects:* Initializes `size_` with `sizeof...(Args)` and `data_` with
+`store.args.data()`.
+``` cpp
+basic_format_arg<Context> get(size_t i) const noexcept;
+```
+*Returns:* `i < size_ ? data_[i] : basic_format_arg<Context>()`.
+[*Note 1*: Implementations are encouraged to optimize the
+representation of `basic_format_args` for small number of formatting
+arguments by storing indices of type alternatives separately from values
+and packing the former. — *end note*]

Diff to HTML by rtfpessoa