[func.wrap.copy] - C++23 → Trunk

Files changed (1) hide show

tmp/tmpblrod_7h/{from.md → to.md} +290 -0

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

	@@ -0,0 +1,290 @@

+#### Copyable wrapper <a id="func.wrap.copy">[[func.wrap.copy]]</a>
+##### General <a id="func.wrap.copy.general">[[func.wrap.copy.general]]</a>
+The header provides partial specializations of `copyable_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 `copyable_function` <a id="func.wrap.copy.class">[[func.wrap.copy.class]]</a>
+``` cpp
+namespace std {
+  template<class R, class... ArgTypes>
+  class copyable_function<R(ArgTypes...) cv ref noexcept(noex)> {
+  public:
+    using result_type = R;
+    // [func.wrap.copy.ctor], constructors, assignments, and destructor
+    copyable_function() noexcept;
+    copyable_function(nullptr_t) noexcept;
+    copyable_function(const copyable_function&);
+    copyable_function(copyable_function&&) noexcept;
+    template<class F> copyable_function(F&&);
+    template<class T, class... Args>
+      explicit copyable_function(in_place_type_t<T>, Args&&...);
+    template<class T, class U, class... Args>
+      explicit copyable_function(in_place_type_t<T>, initializer_list<U>, Args&&...);
+    copyable_function& operator=(const copyable_function&);
+    copyable_function& operator=(copyable_function&&);
+    copyable_function& operator=(nullptr_t) noexcept;
+    template<class F> copyable_function& operator=(F&&);
+    ~copyable_function();
+    // [func.wrap.copy.inv], invocation
+    explicit operator bool() const noexcept;
+    R operator()(ArgTypes...) cv ref noexcept(noex);
+    // [func.wrap.copy.util], utility
+    void swap(copyable_function&) noexcept;
+    friend void swap(copyable_function&, copyable_function&) noexcept;
+    friend bool operator==(const copyable_function&, nullptr_t) noexcept;
+  private:
+    template<class VT>
+      static constexpr bool is-callable-from = see below;       // exposition only
+  };
+}
+```
+The `copyable_function` class template provides polymorphic wrappers
+that generalize the notion of a callable object [[func.def]]. These
+wrappers can store, copy, 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, assignments, and destructor <a id="func.wrap.copy.ctor">[[func.wrap.copy.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
+copyable_function() noexcept;
+copyable_function(nullptr_t) noexcept;
+```
+*Ensures:* `*this` has no target object.
+``` cpp
+copyable_function(const copyable_function& f);
+```
+*Ensures:* `*this` has no target object if `f` had no target object.
+Otherwise, the target object of `*this` is a copy of the target object
+of `f`.
+*Throws:* Any exception thrown by the initialization of the target
+object. May throw `bad_alloc`.
+``` cpp
+copyable_function(copyable_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> copyable_function(F&& f);
+```
+Let `VT` be `decay_t<F>`.
+*Constraints:*
+- `remove_cvref_t<F>` is not the same type as `copyable_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`, and
+- `is_copy_constructible_v<VT>` is `true`.
+*Preconditions:* `VT` meets the *Cpp17Destructible* and
+*Cpp17CopyConstructible* 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 `copyable_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 copyable_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`, and
+- `is_copy_constructible_v<VT>` is `true`.
+*Preconditions:* `VT` meets the *Cpp17Destructible* and
+*Cpp17CopyConstructible* 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 pointer or a
+specialization of `reference_wrapper`.
+``` cpp
+template<class T, class U, class... Args>
+  explicit copyable_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`, and
+- `is_copy_constructible_v<VT>` is `true`.
+*Preconditions:* `VT` meets the *Cpp17Destructible* and
+*Cpp17CopyConstructible* 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 pointer or a
+specialization of `reference_wrapper`.
+``` cpp
+copyable_function& operator=(const copyable_function& f);
+```
+*Effects:* Equivalent to: `copyable_function(f).swap(*this);`
+*Returns:* `*this`.
+``` cpp
+copyable_function& operator=(copyable_function&& f);
+```
+*Effects:* Equivalent to: `copyable_function(std::move(f)).swap(*this);`
+*Returns:* `*this`.
+``` cpp
+copyable_function& operator=(nullptr_t) noexcept;
+```
+*Effects:* Destroys the target object of `*this`, if any.
+*Returns:* `*this`.
+``` cpp
+template<class F> copyable_function& operator=(F&& f);
+```
+*Effects:* Equivalent to:
+`copyable_function(std::forward<F>(f)).swap(*this);`
+*Returns:* `*this`.
+``` cpp
+~copyable_function();
+```
+*Effects:* Destroys the target object of `*this`, if any.
+##### Invocation <a id="func.wrap.copy.inv">[[func.wrap.copy.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.copy.util">[[func.wrap.copy.util]]</a>
+``` cpp
+void swap(copyable_function& other) noexcept;
+```
+*Effects:* Exchanges the target objects of `*this` and `other`.
+``` cpp
+friend void swap(copyable_function& f1, copyable_function& f2) noexcept;
+```
+*Effects:* Equivalent to `f1.swap(f2)`.
+``` cpp
+friend bool operator==(const copyable_function& f, nullptr_t) noexcept;
+```
+*Returns:* `true` if `f` has no target object, otherwise `false`.

Diff to HTML by rtfpessoa