[func.wrap] - C++20 → C++23

Files changed (1) hide show

tmp/tmpnp7cdv59/{from.md → to.md} +325 -45

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

@@ -1,9 +1,11 @@
 ### Polymorphic function wrappers <a id="func.wrap">[[func.wrap]]</a>
-This subclause describes a polymorphic wrapper class that encapsulates
-arbitrary callable objects.
 #### Class `bad_function_call` <a id="func.wrap.badcall">[[func.wrap.badcall]]</a>
 An exception of type `bad_function_call` is thrown by
 `function::operator()` [[func.wrap.func.inv]] when the function wrapper
@@ -25,10 +27,12 @@ const char* what() const noexcept override;
 *Returns:* An *implementation-defined* NTBS.
 #### Class template `function` <a id="func.wrap.func">[[func.wrap.func]]</a>
 ``` cpp
 namespace std {
   template<class> class function;       // not defined
   template<class R, class... ArgTypes>
@@ -39,11 +43,11 @@ namespace std {
     // [func.wrap.func.con], construct/copy/destroy
     function() noexcept;
     function(nullptr_t) noexcept;
     function(const function&);
     function(function&&) noexcept;
-    template<class F> function(F);
     function& operator=(const function&);
     function& operator=(function&&);
     function& operator=(nullptr_t) noexcept;
     template<class F> function& operator=(F&&);
@@ -68,36 +72,29 @@ namespace std {
   template<class R, class... ArgTypes>
     function(R(*)(ArgTypes...)) -> function<R(ArgTypes...)>;
   template<class F> function(F) -> function<see below>;
-  // [func.wrap.func.nullptr], null pointer comparison functions
-  template<class R, class... ArgTypes>
-    bool operator==(const function<R(ArgTypes...)>&, nullptr_t) noexcept;
-  // [func.wrap.func.alg], specialized algorithms
-  template<class R, class... ArgTypes>
-    void swap(function<R(ArgTypes...)>&, function<R(ArgTypes...)>&) noexcept;
 }
 ```
 The `function` class template provides polymorphic wrappers that
 generalize the notion of a function pointer. Wrappers can store, copy,
 and call arbitrary callable objects [[func.def]], given a call signature
-[[func.def]], allowing functions to be first-class objects.
 A callable type [[func.def]] `F` is *Lvalue-Callable* for argument types
 `ArgTypes` and return type `R` if the expression
 `INVOKE<R>(declval<F&>(), declval<ArgTypes>()...)`, considered as an
-unevaluated operand [[expr.prop]], is well-formed [[func.require]].
 The `function` class template is a call wrapper [[func.def]] whose call
 signature [[func.def]] is `R(ArgTypes...)`.
-[*Note 1*: The types deduced by the deduction guides for `function` may
-change in future versions of this International Standard. — *end note*]
 ##### Constructors and destructor <a id="func.wrap.func.con">[[func.wrap.func.con]]</a>
 ``` cpp
 function() noexcept;
@@ -113,70 +110,87 @@ function(nullptr_t) noexcept;
 ``` cpp
 function(const function& f);
 ```
-*Ensures:* `!*this` if `!f`; otherwise, `*this` targets a copy of
-`f.target()`.
 *Throws:* Nothing if `f`’s target is a specialization of
 `reference_wrapper` or a function pointer. Otherwise, may throw
 `bad_alloc` or any exception thrown by the copy constructor of the
 stored callable object.
-[*Note 1*: Implementations should avoid the use of dynamically
-allocated memory for small callable objects, for example, where `f`’s
-target is an object holding only a pointer or reference to an object and
-a member function pointer. — *end note*]
 ``` cpp
 function(function&& f) noexcept;
 ```
 *Ensures:* If `!f`, `*this` has no target; otherwise, the target of
 `*this` is equivalent to the target of `f` before the construction, and
 `f` is in a valid state with an unspecified value.
-[*Note 2*: Implementations should avoid the use of dynamically
-allocated memory for small callable objects, for example, where `f`’s
-target is an object holding only a pointer or reference to an object and
-a member function pointer. — *end note*]
 ``` cpp
-template<class F> function(F f);
 ```
-*Constraints:* `F` is Lvalue-Callable [[func.wrap.func]] for argument
-types `ArgTypes...` and return type `R`.
-*Preconditions:* `F` meets the *Cpp17CopyConstructible* requirements.
-*Ensures:* `!*this` if any of the following hold:
 - `f` is a null function pointer value.
 - `f` is a null member pointer value.
-- `F` is an instance of the `function` class template, and `!f`.
-Otherwise, `*this` targets a copy of `f` initialized with
-`std::move(f)`.
-[*Note 3*: Implementations should avoid the use of dynamically
-allocated memory for small callable objects, for example, where `f` is
-an object holding only a pointer or reference to an object and a member
-function pointer. — *end note*]
-*Throws:* Nothing if `f` is a specialization of `reference_wrapper` or a
-function pointer. Otherwise, may throw `bad_alloc` or any exception
-thrown by `F`’s copy or move constructor.
 ``` cpp
 template<class F> function(F) -> function<see below>;
 ```
 *Constraints:* `&F::operator()` is well-formed when treated as an
-unevaluated operand and `decltype(&F::operator())` is of the form
-`R(G::*)(A...)` cv \\ₒₚₜ ` `noexceptₒₚₜ  for a class type `G`.
 *Remarks:* The deduced type is `function<R(A...)>`.
 [*Example 1*:
@@ -244,11 +258,11 @@ template<class F> function& operator=(reference_wrapper<F> f) noexcept;
 ``` cpp
 void swap(function& other) noexcept;
 ```
-*Effects:* Interchanges the targets of `*this` and `other`.
 ##### Capacity <a id="func.wrap.func.cap">[[func.wrap.func.cap]]</a>
 ``` cpp
 explicit operator bool() const noexcept;
@@ -265,11 +279,11 @@ R operator()(ArgTypes... args) const;
 *Returns:* *INVOKE*\<R\>(f,
 std::forward\<ArgTypes\>(args)...) [[func.require]], where `f` is the
 target object [[func.def]] of `*this`.
 *Throws:* `bad_function_call` if `!*this`; otherwise, any exception
-thrown by the wrapped callable object.
 ##### Target access <a id="func.wrap.func.targ">[[func.wrap.func.targ]]</a>
 ``` cpp
 const type_info& target_type() const noexcept;
@@ -284,11 +298,11 @@ template<class T> const T* target() const noexcept;
 ```
 *Returns:* If `target_type() == typeid(T)` a pointer to the stored
 function target; otherwise a null pointer.
-##### Null pointer comparison functions <a id="func.wrap.func.nullptr">[[func.wrap.func.nullptr]]</a>
 ``` cpp
 template<class R, class... ArgTypes>
   bool operator==(const function<R(ArgTypes...)>& f, nullptr_t) noexcept;
 ```
@@ -302,5 +316,271 @@ template<class R, class... ArgTypes>
   void swap(function<R(ArgTypes...)>& f1, function<R(ArgTypes...)>& f2) noexcept;
 ```
 *Effects:* As if by: `f1.swap(f2);`

 ### Polymorphic function wrappers <a id="func.wrap">[[func.wrap]]</a>
+#### General <a id="func.wrap.general">[[func.wrap.general]]</a>
+Subclause [[func.wrap]] describes polymorphic wrapper classes that
+encapsulate arbitrary callable objects.
 #### Class `bad_function_call` <a id="func.wrap.badcall">[[func.wrap.badcall]]</a>
 An exception of type `bad_function_call` is thrown by
 `function::operator()` [[func.wrap.func.inv]] when the function wrapper
 *Returns:* An *implementation-defined* NTBS.
 #### Class template `function` <a id="func.wrap.func">[[func.wrap.func]]</a>
+##### General <a id="func.wrap.func.general">[[func.wrap.func.general]]</a>
 ``` cpp
 namespace std {
   template<class> class function;       // not defined
   template<class R, class... ArgTypes>
     // [func.wrap.func.con], construct/copy/destroy
     function() noexcept;
     function(nullptr_t) noexcept;
     function(const function&);
     function(function&&) noexcept;
+    template<class F> function(F&&);
     function& operator=(const function&);
     function& operator=(function&&);
     function& operator=(nullptr_t) noexcept;
     template<class F> function& operator=(F&&);
   template<class R, class... ArgTypes>
     function(R(*)(ArgTypes...)) -> function<R(ArgTypes...)>;
   template<class F> function(F) -> function<see below>;
 }
 ```
 The `function` class template provides polymorphic wrappers that
 generalize the notion of a function pointer. Wrappers can store, copy,
 and call arbitrary callable objects [[func.def]], given a call signature
+[[func.def]].
 A callable type [[func.def]] `F` is *Lvalue-Callable* for argument types
 `ArgTypes` and return type `R` if the expression
 `INVOKE<R>(declval<F&>(), declval<ArgTypes>()...)`, considered as an
+unevaluated operand [[term.unevaluated.operand]], is well-formed
+[[func.require]].
 The `function` class template is a call wrapper [[func.def]] whose call
 signature [[func.def]] is `R(ArgTypes...)`.
+[*Note 1*: The types deduced by the deduction guides for `function`
+might change in future revisions of C++. — *end note*]
 ##### Constructors and destructor <a id="func.wrap.func.con">[[func.wrap.func.con]]</a>
 ``` cpp
 function() noexcept;
 ``` cpp
 function(const function& f);
 ```
+*Ensures:* `!*this` if `!f`; otherwise, the target object of `*this` is
+a copy of `f.target()`.
 *Throws:* Nothing if `f`’s target is a specialization of
 `reference_wrapper` or a function pointer. Otherwise, may throw
 `bad_alloc` or any exception thrown by the copy constructor of the
 stored callable object.
+*Recommended practice:* Implementations should avoid the use of
+dynamically allocated memory for small callable objects, for example,
+where `f`’s target is an object holding only a pointer or reference to
+an object and a member function pointer.
 ``` cpp
 function(function&& f) noexcept;
 ```
 *Ensures:* If `!f`, `*this` has no target; otherwise, the target of
 `*this` is equivalent to the target of `f` before the construction, and
 `f` is in a valid state with an unspecified value.
+*Recommended practice:* Implementations should avoid the use of
+dynamically allocated memory for small callable objects, for example,
+where `f`’s target is an object holding only a pointer or reference to
+an object and a member function pointer.
 ``` cpp
+template<class F> function(F&& f);
 ```
+Let `FD` be `decay_t<F>`.
+*Constraints:*
+- `is_same_v<remove_cvref_t<F>, function>` is `false`, and
+- `FD` is Lvalue-Callable [[func.wrap.func]] for argument types
+  `ArgTypes...` and return type `R`.
+*Mandates:*
+- `is_copy_constructible_v<FD>` is `true`, and
+- `is_constructible_v<FD, F>` is `true`.
+*Preconditions:* `FD` meets the *Cpp17CopyConstructible* requirements.
+*Ensures:* `!*this` is `true` if any of the following hold:
 - `f` is a null function pointer value.
 - `f` is a null member pointer value.
+- `remove_cvref_t<F>` is a specialization of the `function` class
+  template, and `!f` is `true`.
+Otherwise, `*this` has a target object of type `FD`
+direct-non-list-initialized with `std::forward<F>(f)`.
+*Throws:* Nothing if `FD` is a specialization of `reference_wrapper` or
+a function pointer type. Otherwise, may throw `bad_alloc` or any
+exception thrown by the initialization of the target object.
+*Recommended practice:* Implementations should avoid the use of
+dynamically allocated memory for small callable objects, for example,
+where `f` refers to an object holding only a pointer or reference to an
+object and a member function pointer.
 ``` cpp
 template<class F> function(F) -> function<see below>;
 ```
 *Constraints:* `&F::operator()` is well-formed when treated as an
+unevaluated operand and either
+- `F::operator()` is a non-static member function and
+  `decltype(&F::operator())` is either of the form
+  `R(G::*)(A...)` cv \\ₒₚₜ ` `noexceptₒₚₜ  or of the form
+  `R(*)(G, A...) `noexceptₒₚₜ  for a type `G`, or
+- `F::operator()` is a static member function and
+  `decltype(&F::operator())` is of the form `R(*)(A...) `noexceptₒₚₜ .
 *Remarks:* The deduced type is `function<R(A...)>`.
 [*Example 1*:
 ``` cpp
 void swap(function& other) noexcept;
 ```
+*Effects:* Interchanges the target objects of `*this` and `other`.
 ##### Capacity <a id="func.wrap.func.cap">[[func.wrap.func.cap]]</a>
 ``` cpp
 explicit operator bool() const noexcept;
 *Returns:* *INVOKE*\<R\>(f,
 std::forward\<ArgTypes\>(args)...) [[func.require]], where `f` is the
 target object [[func.def]] of `*this`.
 *Throws:* `bad_function_call` if `!*this`; otherwise, any exception
+thrown by the target object.
 ##### Target access <a id="func.wrap.func.targ">[[func.wrap.func.targ]]</a>
 ``` cpp
 const type_info& target_type() const noexcept;
 ```
 *Returns:* If `target_type() == typeid(T)` a pointer to the stored
 function target; otherwise a null pointer.
+##### Null pointer comparison operator functions <a id="func.wrap.func.nullptr">[[func.wrap.func.nullptr]]</a>
 ``` cpp
 template<class R, class... ArgTypes>
   bool operator==(const function<R(ArgTypes...)>& f, nullptr_t) noexcept;
 ```
   void swap(function<R(ArgTypes...)>& f1, function<R(ArgTypes...)>& f2) noexcept;
 ```
 *Effects:* As if by: `f1.swap(f2);`
+#### Move only wrapper <a id="func.wrap.move">[[func.wrap.move]]</a>
+##### General <a id="func.wrap.move.general">[[func.wrap.move.general]]</a>
+The header provides partial specializations of `move_only_function` for
+each combination of the possible replacements of the placeholders cv,
+*ref*, and *noex* where
+- cv is either const or empty,
+- *ref* is either `&`, `&&`, or empty, and
+- *noex* is either `true` or `false`.
+For each of the possible combinations of the placeholders mentioned
+above, there is a placeholder *inv-quals* defined as follows:
+- If *ref* is empty, let *inv-quals* be cv`&`,
+- otherwise, let *inv-quals* be cv *ref*.
+##### Class template `move_only_function` <a id="func.wrap.move.class">[[func.wrap.move.class]]</a>
+``` cpp
+namespace std {
+  template<class... S> class move_only_function;                // not defined
+  template<class R, class... ArgTypes>
+  class move_only_function<R(ArgTypes...) cv ref noexcept(noex)> {
+  public:
+    using result_type = R;
+    // [func.wrap.move.ctor], constructors, assignment, and destructor
+    move_only_function() noexcept;
+    move_only_function(nullptr_t) noexcept;
+    move_only_function(move_only_function&&) noexcept;
+    template<class F> move_only_function(F&&);
+    template<class T, class... Args>
+      explicit move_only_function(in_place_type_t<T>, Args&&...);
+    template<class T, class U, class... Args>
+      explicit move_only_function(in_place_type_t<T>, initializer_list<U>, Args&&...);
+    move_only_function& operator=(move_only_function&&);
+    move_only_function& operator=(nullptr_t) noexcept;
+    template<class F> move_only_function& operator=(F&&);
+    ~move_only_function();
+    // [func.wrap.move.inv], invocation
+    explicit operator bool() const noexcept;
+    R operator()(ArgTypes...) cv ref noexcept(noex);
+    // [func.wrap.move.util], utility
+    void swap(move_only_function&) noexcept;
+    friend void swap(move_only_function&, move_only_function&) noexcept;
+    friend bool operator==(const move_only_function&, nullptr_t) noexcept;
+  private:
+    template<class VT>
+      static constexpr bool is-callable-from = see below;       // exposition only
+  };
+}
+```
+The `move_only_function` class template provides polymorphic wrappers
+that generalize the notion of a callable object [[func.def]]. These
+wrappers can store, move, and call arbitrary callable objects, given a
+call signature.
+*Recommended practice:* Implementations should avoid the use of
+dynamically allocated memory for a small contained value.
+[*Note 1*: Such small-object optimization can only be applied to a type
+`T` for which `is_nothrow_move_constructible_v<T>` is
+`true`. — *end note*]
+##### Constructors, assignment, and destructor <a id="func.wrap.move.ctor">[[func.wrap.move.ctor]]</a>
+``` cpp
+template<class VT>
+  static constexpr bool is-callable-from = see below;
+```
+If *noex* is `true`, *`is-callable-from`*`<VT>` is equal to:
+``` cpp
+is_nothrow_invocable_r_v<R, VT cv ref, ArgTypes...> &&
+is_nothrow_invocable_r_v<R, VT inv-quals, ArgTypes...>
+```
+Otherwise, *`is-callable-from`*`<VT>` is equal to:
+``` cpp
+is_invocable_r_v<R, VT cv ref, ArgTypes...> &&
+is_invocable_r_v<R, VT inv-quals, ArgTypes...>
+```
+``` cpp
+move_only_function() noexcept;
+move_only_function(nullptr_t) noexcept;
+```
+*Ensures:* `*this` has no target object.
+``` cpp
+move_only_function(move_only_function&& f) noexcept;
+```
+*Ensures:* The target object of `*this` is the target object `f` had
+before construction, and `f` is in a valid state with an unspecified
+value.
+``` cpp
+template<class F> move_only_function(F&& f);
+```
+Let `VT` be `decay_t<F>`.
+*Constraints:*
+- `remove_cvref_t<F>` is not the same type as `move_only_function`, and
+- `remove_cvref_t<F>` is not a specialization of `in_place_type_t`, and
+- *`is-callable-from`*`<VT>` is `true`.
+*Mandates:* `is_constructible_v<VT, F>` is `true`.
+*Preconditions:* `VT` meets the *Cpp17Destructible* requirements, and if
+`is_move_constructible_v<VT>` is `true`, `VT` meets the
+*Cpp17MoveConstructible* requirements.
+*Ensures:* `*this` has no target object if any of the following hold:
+- `f` is a null function pointer value, or
+- `f` is a null member pointer value, or
+- `remove_cvref_t<F>` is a specialization of the `move_only_function`
+  class template, and `f` has no target object.
+Otherwise, `*this` has a target object of type `VT`
+direct-non-list-initialized with `std::forward<F>(f)`.
+*Throws:* Any exception thrown by the initialization of the target
+object. May throw `bad_alloc` unless `VT` is a function pointer or a
+specialization of `reference_wrapper`.
+``` cpp
+template<class T, class... Args>
+  explicit move_only_function(in_place_type_t<T>, Args&&... args);
+```
+Let `VT` be `decay_t<T>`.
+*Constraints:*
+- `is_constructible_v<VT, Args...>` is `true`, and
+- *`is-callable-from`*`<VT>` is `true`.
+*Mandates:* `VT` is the same type as `T`.
+*Preconditions:* `VT` meets the *Cpp17Destructible* requirements, and if
+`is_move_constructible_v<VT>` is `true`, `VT` meets the
+*Cpp17MoveConstructible* requirements.
+*Ensures:* `*this` has a target object of type `VT`
+direct-non-list-initialized with `std::forward<Args>(args)...`.
+*Throws:* Any exception thrown by the initialization of the target
+object. May throw `bad_alloc` unless `VT` is a function pointer or a
+specialization of `reference_wrapper`.
+``` cpp
+template<class T, class U, class... Args>
+  explicit move_only_function(in_place_type_t<T>, initializer_list<U> ilist, Args&&... args);
+```
+Let `VT` be `decay_t<T>`.
+*Constraints:*
+- `is_constructible_v<VT, initializer_list<U>&, Args...>` is `true`, and
+- *`is-callable-from`*`<VT>` is `true`.
+*Mandates:* `VT` is the same type as `T`.
+*Preconditions:* `VT` meets the *Cpp17Destructible* requirements, and if
+`is_move_constructible_v<VT>` is `true`, `VT` meets the
+*Cpp17MoveConstructible* requirements.
+*Ensures:* `*this` has a target object of type `VT`
+direct-non-list-initialized with `ilist, std::forward<Args>(args)...`.
+*Throws:* Any exception thrown by the initialization of the target
+object. May throw `bad_alloc` unless `VT` is a function pointer or a
+specialization of `reference_wrapper`.
+``` cpp
+move_only_function& operator=(move_only_function&& f);
+```
+*Effects:* Equivalent to:
+`move_only_function(std::move(f)).swap(*this);`
+*Returns:* `*this`.
+``` cpp
+move_only_function& operator=(nullptr_t) noexcept;
+```
+*Effects:* Destroys the target object of `*this`, if any.
+*Returns:* `*this`.
+``` cpp
+template<class F> move_only_function& operator=(F&& f);
+```
+*Effects:* Equivalent to:
+`move_only_function(std::forward<F>(f)).swap(*this);`
+*Returns:* `*this`.
+``` cpp
+~move_only_function();
+```
+*Effects:* Destroys the target object of `*this`, if any.
+##### Invocation <a id="func.wrap.move.inv">[[func.wrap.move.inv]]</a>
+``` cpp
+explicit operator bool() const noexcept;
+```
+*Returns:* `true` if `*this` has a target object, otherwise `false`.
+``` cpp
+R operator()(ArgTypes... args) cv ref noexcept(noex);
+```
+*Preconditions:* `*this` has a target object.
+*Effects:* Equivalent to:
+``` cpp
+return INVOKE<R>(static_cast<F inv-quals>(f), std::forward<ArgTypes>(args)...);
+```
+where `f` is an lvalue designating the target object of `*this` and `F`
+is the type of `f`.
+##### Utility <a id="func.wrap.move.util">[[func.wrap.move.util]]</a>
+``` cpp
+void swap(move_only_function& other) noexcept;
+```
+*Effects:* Exchanges the target objects of `*this` and `other`.
+``` cpp
+friend void swap(move_only_function& f1, move_only_function& f2) noexcept;
+```
+*Effects:* Equivalent to `f1.swap(f2)`.
+``` cpp
+friend bool operator==(const move_only_function& f, nullptr_t) noexcept;
+```
+*Returns:* `true` if `f` has no target object, otherwise `false`.

Diff to HTML by rtfpessoa