From Jason Turner

[func.wrap.func]

C++20 → C++23 8.5 KB 107 lines
Current Draft | LaTeX Source
Archived: C++20 | C++23
Markdown: C++20 | C++23
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmppo7ldmfs/{from.md → to.md} +55 -43
tmp/tmppo7ldmfs/{from.md → to.md} RENAMED
@@ -1,7 +1,9 @@
1
  #### Class template `function` <a id="func.wrap.func">[[func.wrap.func]]</a>
2
 
 
 
3
  ``` cpp
4
  namespace std {
5
  template<class> class function; // not defined
6
 
7
  template<class R, class... ArgTypes>
@@ -12,11 +14,11 @@ namespace std {
12
  // [func.wrap.func.con], construct/copy/destroy
13
  function() noexcept;
14
  function(nullptr_t) noexcept;
15
  function(const function&);
16
  function(function&&) noexcept;
17
- template<class F> function(F);
18
 
19
  function& operator=(const function&);
20
  function& operator=(function&&);
21
  function& operator=(nullptr_t) noexcept;
22
  template<class F> function& operator=(F&&);
@@ -41,36 +43,29 @@ namespace std {
41
 
42
  template<class R, class... ArgTypes>
43
  function(R(*)(ArgTypes...)) -> function<R(ArgTypes...)>;
44
 
45
  template<class F> function(F) -> function<see below>;
46
-
47
- // [func.wrap.func.nullptr], null pointer comparison functions
48
- template<class R, class... ArgTypes>
49
- bool operator==(const function<R(ArgTypes...)>&, nullptr_t) noexcept;
50
-
51
- // [func.wrap.func.alg], specialized algorithms
52
- template<class R, class... ArgTypes>
53
- void swap(function<R(ArgTypes...)>&, function<R(ArgTypes...)>&) noexcept;
54
  }
55
  ```
56
 
57
  The `function` class template provides polymorphic wrappers that
58
  generalize the notion of a function pointer. Wrappers can store, copy,
59
  and call arbitrary callable objects [[func.def]], given a call signature
60
- [[func.def]], allowing functions to be first-class objects.
61
 
62
  A callable type [[func.def]] `F` is *Lvalue-Callable* for argument types
63
  `ArgTypes` and return type `R` if the expression
64
  `INVOKE<R>(declval<F&>(), declval<ArgTypes>()...)`, considered as an
65
- unevaluated operand [[expr.prop]], is well-formed [[func.require]].
 
66
 
67
  The `function` class template is a call wrapper [[func.def]] whose call
68
  signature [[func.def]] is `R(ArgTypes...)`.
69
 
70
- [*Note 1*: The types deduced by the deduction guides for `function` may
71
- change in future versions of this International Standard. — *end note*]
72
 
73
  ##### Constructors and destructor <a id="func.wrap.func.con">[[func.wrap.func.con]]</a>
74
 
75
  ``` cpp
76
  function() noexcept;
@@ -86,70 +81,87 @@ function(nullptr_t) noexcept;
86
 
87
  ``` cpp
88
  function(const function& f);
89
  ```
90
 
91
- *Ensures:* `!*this` if `!f`; otherwise, `*this` targets a copy of
92
- `f.target()`.
93
 
94
  *Throws:* Nothing if `f`’s target is a specialization of
95
  `reference_wrapper` or a function pointer. Otherwise, may throw
96
  `bad_alloc` or any exception thrown by the copy constructor of the
97
  stored callable object.
98
 
99
- [*Note 1*: Implementations should avoid the use of dynamically
100
- allocated memory for small callable objects, for example, where `f`’s
101
- target is an object holding only a pointer or reference to an object and
102
- a member function pointer. — *end note*]
103
 
104
  ``` cpp
105
  function(function&& f) noexcept;
106
  ```
107
 
108
  *Ensures:* If `!f`, `*this` has no target; otherwise, the target of
109
  `*this` is equivalent to the target of `f` before the construction, and
110
  `f` is in a valid state with an unspecified value.
111
 
112
- [*Note 2*: Implementations should avoid the use of dynamically
113
- allocated memory for small callable objects, for example, where `f`’s
114
- target is an object holding only a pointer or reference to an object and
115
- a member function pointer. — *end note*]
116
 
117
  ``` cpp
118
- template<class F> function(F f);
119
  ```
120
 
121
- *Constraints:* `F` is Lvalue-Callable [[func.wrap.func]] for argument
122
- types `ArgTypes...` and return type `R`.
123
 
124
- *Preconditions:* `F` meets the *Cpp17CopyConstructible* requirements.
125
 
126
- *Ensures:* `!*this` if any of the following hold:
 
 
 
 
 
 
 
 
 
 
 
127
 
128
  - `f` is a null function pointer value.
129
  - `f` is a null member pointer value.
130
- - `F` is an instance of the `function` class template, and `!f`.
 
131
 
132
- Otherwise, `*this` targets a copy of `f` initialized with
133
- `std::move(f)`.
134
 
135
- [*Note 3*: Implementations should avoid the use of dynamically
136
- allocated memory for small callable objects, for example, where `f` is
137
- an object holding only a pointer or reference to an object and a member
138
- function pointer. — *end note*]
139
 
140
- *Throws:* Nothing if `f` is a specialization of `reference_wrapper` or a
141
- function pointer. Otherwise, may throw `bad_alloc` or any exception
142
- thrown by `F`’s copy or move constructor.
 
143
 
144
  ``` cpp
145
  template<class F> function(F) -> function<see below>;
146
  ```
147
 
148
  *Constraints:* `&F::operator()` is well-formed when treated as an
149
- unevaluated operand and `decltype(&F::operator())` is of the form
150
- `R(G::*)(A...)` cv \\ₒₚₜ ` `noexceptₒₚₜ for a class type `G`.
 
 
 
 
 
 
151
 
152
  *Remarks:* The deduced type is `function<R(A...)>`.
153
 
154
  [*Example 1*:
155
 
@@ -217,11 +229,11 @@ template<class F> function& operator=(reference_wrapper<F> f) noexcept;
217
 
218
  ``` cpp
219
  void swap(function& other) noexcept;
220
  ```
221
 
222
- *Effects:* Interchanges the targets of `*this` and `other`.
223
 
224
  ##### Capacity <a id="func.wrap.func.cap">[[func.wrap.func.cap]]</a>
225
 
226
  ``` cpp
227
  explicit operator bool() const noexcept;
@@ -238,11 +250,11 @@ R operator()(ArgTypes... args) const;
238
  *Returns:* *INVOKE*\<R\>(f,
239
  std::forward\<ArgTypes\>(args)...) [[func.require]], where `f` is the
240
  target object [[func.def]] of `*this`.
241
 
242
  *Throws:* `bad_function_call` if `!*this`; otherwise, any exception
243
- thrown by the wrapped callable object.
244
 
245
  ##### Target access <a id="func.wrap.func.targ">[[func.wrap.func.targ]]</a>
246
 
247
  ``` cpp
248
  const type_info& target_type() const noexcept;
@@ -257,11 +269,11 @@ template<class T> const T* target() const noexcept;
257
  ```
258
 
259
  *Returns:* If `target_type() == typeid(T)` a pointer to the stored
260
  function target; otherwise a null pointer.
261
 
262
- ##### Null pointer comparison functions <a id="func.wrap.func.nullptr">[[func.wrap.func.nullptr]]</a>
263
 
264
  ``` cpp
265
  template<class R, class... ArgTypes>
266
  bool operator==(const function<R(ArgTypes...)>& f, nullptr_t) noexcept;
267
  ```
 
1
  #### Class template `function` <a id="func.wrap.func">[[func.wrap.func]]</a>
2
 
3
+ ##### General <a id="func.wrap.func.general">[[func.wrap.func.general]]</a>
4
+
5
  ``` cpp
6
  namespace std {
7
  template<class> class function; // not defined
8
 
9
  template<class R, class... ArgTypes>
 
14
  // [func.wrap.func.con], construct/copy/destroy
15
  function() noexcept;
16
  function(nullptr_t) noexcept;
17
  function(const function&);
18
  function(function&&) noexcept;
19
+ template<class F> function(F&&);
20
 
21
  function& operator=(const function&);
22
  function& operator=(function&&);
23
  function& operator=(nullptr_t) noexcept;
24
  template<class F> function& operator=(F&&);
 
43
 
44
  template<class R, class... ArgTypes>
45
  function(R(*)(ArgTypes...)) -> function<R(ArgTypes...)>;
46
 
47
  template<class F> function(F) -> function<see below>;
 
 
 
 
 
 
 
 
48
  }
49
  ```
50
 
51
  The `function` class template provides polymorphic wrappers that
52
  generalize the notion of a function pointer. Wrappers can store, copy,
53
  and call arbitrary callable objects [[func.def]], given a call signature
54
+ [[func.def]].
55
 
56
  A callable type [[func.def]] `F` is *Lvalue-Callable* for argument types
57
  `ArgTypes` and return type `R` if the expression
58
  `INVOKE<R>(declval<F&>(), declval<ArgTypes>()...)`, considered as an
59
+ unevaluated operand [[term.unevaluated.operand]], is well-formed
60
+ [[func.require]].
61
 
62
  The `function` class template is a call wrapper [[func.def]] whose call
63
  signature [[func.def]] is `R(ArgTypes...)`.
64
 
65
+ [*Note 1*: The types deduced by the deduction guides for `function`
66
+ might change in future revisions of C++. — *end note*]
67
 
68
  ##### Constructors and destructor <a id="func.wrap.func.con">[[func.wrap.func.con]]</a>
69
 
70
  ``` cpp
71
  function() noexcept;
 
81
 
82
  ``` cpp
83
  function(const function& f);
84
  ```
85
 
86
+ *Ensures:* `!*this` if `!f`; otherwise, the target object of `*this` is
87
+ a copy of `f.target()`.
88
 
89
  *Throws:* Nothing if `f`’s target is a specialization of
90
  `reference_wrapper` or a function pointer. Otherwise, may throw
91
  `bad_alloc` or any exception thrown by the copy constructor of the
92
  stored callable object.
93
 
94
+ *Recommended practice:* Implementations should avoid the use of
95
+ dynamically allocated memory for small callable objects, for example,
96
+ where `f`’s target is an object holding only a pointer or reference to
97
+ an object and a member function pointer.
98
 
99
  ``` cpp
100
  function(function&& f) noexcept;
101
  ```
102
 
103
  *Ensures:* If `!f`, `*this` has no target; otherwise, the target of
104
  `*this` is equivalent to the target of `f` before the construction, and
105
  `f` is in a valid state with an unspecified value.
106
 
107
+ *Recommended practice:* Implementations should avoid the use of
108
+ dynamically allocated memory for small callable objects, for example,
109
+ where `f`’s target is an object holding only a pointer or reference to
110
+ an object and a member function pointer.
111
 
112
  ``` cpp
113
+ template<class F> function(F&& f);
114
  ```
115
 
116
+ Let `FD` be `decay_t<F>`.
 
117
 
118
+ *Constraints:*
119
 
120
+ - `is_same_v<remove_cvref_t<F>, function>` is `false`, and
121
+ - `FD` is Lvalue-Callable [[func.wrap.func]] for argument types
122
+ `ArgTypes...` and return type `R`.
123
+
124
+ *Mandates:*
125
+
126
+ - `is_copy_constructible_v<FD>` is `true`, and
127
+ - `is_constructible_v<FD, F>` is `true`.
128
+
129
+ *Preconditions:* `FD` meets the *Cpp17CopyConstructible* requirements.
130
+
131
+ *Ensures:* `!*this` is `true` if any of the following hold:
132
 
133
  - `f` is a null function pointer value.
134
  - `f` is a null member pointer value.
135
+ - `remove_cvref_t<F>` is a specialization of the `function` class
136
+ template, and `!f` is `true`.
137
 
138
+ Otherwise, `*this` has a target object of type `FD`
139
+ direct-non-list-initialized with `std::forward<F>(f)`.
140
 
141
+ *Throws:* Nothing if `FD` is a specialization of `reference_wrapper` or
142
+ a function pointer type. Otherwise, may throw `bad_alloc` or any
143
+ exception thrown by the initialization of the target object.
 
144
 
145
+ *Recommended practice:* Implementations should avoid the use of
146
+ dynamically allocated memory for small callable objects, for example,
147
+ where `f` refers to an object holding only a pointer or reference to an
148
+ object and a member function pointer.
149
 
150
  ``` cpp
151
  template<class F> function(F) -> function<see below>;
152
  ```
153
 
154
  *Constraints:* `&F::operator()` is well-formed when treated as an
155
+ unevaluated operand and either
156
+
157
+ - `F::operator()` is a non-static member function and
158
+ `decltype(&F::operator())` is either of the form
159
+ `R(G::*)(A...)` cv \\ₒₚₜ ` `noexceptₒₚₜ or of the form
160
+ `R(*)(G, A...) `noexceptₒₚₜ for a type `G`, or
161
+ - `F::operator()` is a static member function and
162
+ `decltype(&F::operator())` is of the form `R(*)(A...) `noexceptₒₚₜ .
163
 
164
  *Remarks:* The deduced type is `function<R(A...)>`.
165
 
166
  [*Example 1*:
167
 
 
229
 
230
  ``` cpp
231
  void swap(function& other) noexcept;
232
  ```
233
 
234
+ *Effects:* Interchanges the target objects of `*this` and `other`.
235
 
236
  ##### Capacity <a id="func.wrap.func.cap">[[func.wrap.func.cap]]</a>
237
 
238
  ``` cpp
239
  explicit operator bool() const noexcept;
 
250
  *Returns:* *INVOKE*\<R\>(f,
251
  std::forward\<ArgTypes\>(args)...) [[func.require]], where `f` is the
252
  target object [[func.def]] of `*this`.
253
 
254
  *Throws:* `bad_function_call` if `!*this`; otherwise, any exception
255
+ thrown by the target object.
256
 
257
  ##### Target access <a id="func.wrap.func.targ">[[func.wrap.func.targ]]</a>
258
 
259
  ``` cpp
260
  const type_info& target_type() const noexcept;
 
269
  ```
270
 
271
  *Returns:* If `target_type() == typeid(T)` a pointer to the stored
272
  function target; otherwise a null pointer.
273
 
274
+ ##### Null pointer comparison operator functions <a id="func.wrap.func.nullptr">[[func.wrap.func.nullptr]]</a>
275
 
276
  ``` cpp
277
  template<class R, class... ArgTypes>
278
  bool operator==(const function<R(ArgTypes...)>& f, nullptr_t) noexcept;
279
  ```