From Jason Turner

[utility.requirements]

C++17 → C++20 21.9 KB 233 lines
Current Draft | LaTeX Source
Archived: C++17 | C++20
Markdown: C++17 | C++20
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmp3_53moqj/{from.md → to.md} +113 -110
tmp/tmp3_53moqj/{from.md → to.md} RENAMED
@@ -12,74 +12,74 @@ allocators.
12
 
13
  #### Template argument requirements <a id="utility.arg.requirements">[[utility.arg.requirements]]</a>
14
 
15
  The template definitions in the C++ standard library refer to various
16
  named requirements whose details are set out in Tables 
17
- [[tab:equalitycomparable]]– [[tab:destructible]]. In these tables, `T`
18
- is an object or reference type to be supplied by a C++program
19
- instantiating a template; `a`, `b`, and `c` are values of type (possibly
20
- `const`) `T`; `s` and `t` are modifiable lvalues of type `T`; `u`
21
- denotes an identifier; `rv` is an rvalue of type `T`; and `v` is an
22
  lvalue of type (possibly `const`) `T` or an rvalue of type `const T`.
23
 
24
  In general, a default constructor is not required. Certain container
25
  class member function signatures specify `T()` as a default argument.
26
- `T()` shall be a well-defined expression ([[dcl.init]]) if one of those
27
- signatures is called using the default argument ([[dcl.fct.default]]).
28
 
29
- **Table: `EqualityComparable` requirements** <a id="equalitycomparable">[equalitycomparable]</a>
30
 
31
  | Expression | Return type |
32
  | ---------- | ----------- |
33
  | `a == b` | convertible to `bool` | `==` is an equivalence relation, that is, it has the following properties: For all `a`, `a == a`.; If `a == b`, then `b == a`.; If `a == b` and `b == c`, then `a == c`. |
34
 
35
- **Table: `LessThanComparable` requirements** <a id="lessthancomparable">[lessthancomparable]</a>
 
36
 
37
  | Expression | Return type | Requirement |
38
- | ---------- | --------------------- | --------------------------------------------------------- |
39
- | `a < b` | convertible to `bool` | `<` is a strict weak ordering relation~([[alg.sorting]]) |
40
 
41
- **Table: `DefaultConstructible` requirements** <a id="defaultconstructible">[defaultconstructible]</a>
 
42
 
43
  | Expression | Post-condition |
44
  | -------------- | ------------------------------------------------------------------- |
45
  | `T t;` | object `t` is default-initialized |
46
  | `T u{};` | object `u` is value-initialized or aggregate-initialized |
47
  | `T()`<br>`T{}` | an object of type `T` is value-initialized or aggregate-initialized |
48
 
 
49
  [*Note 1*: `rv` must still meet the requirements of the library
50
  component that is using it. The operations listed in those requirements
51
  must work as specified whether `rv` has been moved from or
52
  not. — *end note*]
53
 
54
- **Table: `CopyConstructible` requirements (in addition to `MoveConstructible`)** <a id="copyconstructible">[copyconstructible]</a>
55
 
56
  | Expression | Post-condition |
57
  | ---------- | --------------------------------------------------------- |
58
  | `T u = v;` | the value of `v` is unchanged and is equivalent to ` u` |
59
  | `T(v)` | the value of `v` is unchanged and is equivalent to `T(v)` |
60
 
 
61
  [*Note 2*:  `rv` must still meet the requirements of the library
62
  component that is using it, whether or not `t` and `rv` refer to the
63
  same object. The operations listed in those requirements must work as
64
  specified whether `rv` has been moved from or not. — *end note*]
65
 
66
- **Table: `CopyAssignable` requirements (in addition to `MoveAssignable`)** <a id="copyassignable">[copyassignable]</a>
67
 
68
  | Expression | Return type | Return value | Post-condition |
69
  | ---------- | ----------- | ------------ | ------------------------------------------------------- |
70
  | `t = v` | `T&` | `t` | `t` is equivalent to `v`, the value of `v` is unchanged |
71
 
72
 
73
- **Table: `Destructible` requirements** <a id="destructible">[destructible]</a>
 
74
 
75
- | Expression | Post-condition |
76
- | ---------- | --------------------------------------------------------------------- |
77
- | `u.~T()` | All resources owned by `u` are reclaimed, no exception is propagated. |
78
-
79
-
80
- #### `Swappable` requirements <a id="swappable.requirements">[[swappable.requirements]]</a>
81
 
82
  This subclause provides definitions for swappable types and expressions.
83
  In these definitions, let `t` denote an expression of type `T`, and let
84
  `u` denote an expression of type `U`.
85
 
@@ -92,16 +92,15 @@ An object `t` is *swappable with* an object `u` if and only if:
92
  and
93
  - the object referred to by `u` has the value originally held by `t`.
94
 
95
  The context in which `swap(t, u)` and `swap(u, t)` are evaluated shall
96
  ensure that a binary non-member function named “swap” is selected via
97
- overload resolution ([[over.match]]) on a candidate set that includes:
98
 
99
- - the two `swap` function templates defined in `<utility>` (
100
- [[utility]]) and
101
- - the lookup set produced by argument-dependent lookup (
102
- [[basic.lookup.argdep]]).
103
 
104
  [*Note 1*: If `T` and `U` are both fundamental types or arrays of
105
  fundamental types and the declarations from the header `<utility>` are
106
  in scope, the overall lookup set described above is equivalent to that
107
  of the qualified name lookup applied to the expression `std::swap(t, u)`
@@ -112,14 +111,13 @@ swappable requirement includes the header `<utility>` to ensure an
112
  appropriate evaluation context. — *end note*]
113
 
114
  An rvalue or lvalue `t` is *swappable* if and only if `t` is swappable
115
  with any rvalue or lvalue, respectively, of type `T`.
116
 
117
- A type `X` satisfying any of the iterator requirements (
118
- [[iterator.requirements]]) satisfies the requirements of
119
- `ValueSwappable` if, for any dereferenceable object `x` of type `X`,
120
- `*x` is swappable.
121
 
122
  [*Example 1*:
123
 
124
  User code can ensure that the evaluation of `swap` calls is performed in
125
  an appropriate context under the various conditions as follows:
@@ -137,12 +135,12 @@ void value_swap(T&& t, U&& u) {
137
 
138
  // Requires: lvalues of T shall be swappable.
139
  template<class T>
140
  void lv_swap(T& t1, T& t2) {
141
  using std::swap;
142
- swap(t1, t2); // OK: uses swappable conditions for
143
- } // lvalues of type T
144
 
145
  namespace N {
146
  struct A { int m; };
147
  struct Proxy { A* a; };
148
  Proxy proxy(A& a) { return Proxy{ &a }; }
@@ -165,103 +163,102 @@ int main() {
165
  }
166
  ```
167
 
168
  — *end example*]
169
 
170
- #### `NullablePointer` requirements <a id="nullablepointer.requirements">[[nullablepointer.requirements]]</a>
171
 
172
- A `NullablePointer` type is a pointer-like type that supports null
173
- values. A type `P` meets the requirements of `NullablePointer` if:
174
 
175
- - `P` satisfies the requirements of `EqualityComparable`,
176
- `DefaultConstructible`, `CopyConstructible`, `CopyAssignable`, and
177
- `Destructible`,
178
- - lvalues of type `P` are swappable ([[swappable.requirements]]),
179
- - the expressions shown in Table  [[tab:nullablepointer]] are valid and
180
- have the indicated semantics, and
181
- - `P` satisfies all the other requirements of this subclause.
182
 
183
  A value-initialized object of type `P` produces the null value of the
184
  type. The null value shall be equivalent only to itself. A
185
  default-initialized object of type `P` may have an indeterminate value.
186
 
187
  [*Note 1*: Operations involving indeterminate values may cause
188
  undefined behavior. — *end note*]
189
 
190
  An object `p` of type `P` can be contextually converted to `bool`
191
- (Clause  [[conv]]). The effect shall be as if `p != nullptr` had been
192
- evaluated in place of `p`.
193
 
194
- No operation which is part of the `NullablePointer` requirements shall
195
- exit via an exception.
196
 
197
- In Table  [[tab:nullablepointer]], `u` denotes an identifier, `t`
198
- denotes a non-`const` lvalue of type `P`, `a` and `b` denote values of
199
- type (possibly `const`) `P`, and `np` denotes a value of type (possibly
200
  `const`) `std::nullptr_t`.
201
 
202
- **Table: `NullablePointer` requirements** <a id="nullablepointer">[nullablepointer]</a>
203
 
204
- | | | |
205
- | -------------- | ---------------------------------- | ---------------------------------- |
206
- | `P u(np);`<br> | | Postconditions: `u == nullptr` |
207
  | `P u = np;` | | |
208
- | `P(np)` | | Postconditions: `P(np) == nullptr` |
209
- | `t = np` | `P&` | Postconditions: `t == nullptr` |
210
  | `a != b` | contextually convertible to `bool` | `!(a == b)` |
211
  | `a == np` | contextually convertible to `bool` | `a == P()` |
212
  | `np == a` | | |
213
  | `a != np` | contextually convertible to `bool` | `!(a == np)` |
214
  | `np != a` | | |
215
 
216
 
217
- #### Hash requirements <a id="hash.requirements">[[hash.requirements]]</a>
218
 
219
- A type `H` meets the `Hash` requirements if:
220
 
221
- - it is a function object type ([[function.objects]]),
222
- - it satisfies the requirements of `CopyConstructible` and
223
- `Destructible` ([[utility.arg.requirements]]), and
224
- - the expressions shown in Table  [[tab:hash]] are valid and have the
225
  indicated semantics.
226
 
227
  Given `Key` is an argument type for function objects of type `H`, in
228
- Table  [[tab:hash]] `h` is a value of type (possibly `const`) `H`, `u`
229
- is an lvalue of type `Key`, and `k` is a value of a type convertible to
230
  (possibly `const`) `Key`.
231
 
232
  [*Note 1*: Thus all evaluations of the expression `h(k)` with the same
233
  value for `k` yield the same result for a given execution of the
234
  program. — *end note*]
235
 
236
- #### Allocator requirements <a id="allocator.requirements">[[allocator.requirements]]</a>
237
 
238
  The library describes a standard set of requirements for *allocators*,
239
  which are class-type objects that encapsulate the information about an
240
  allocation model. This information includes the knowledge of pointer
241
  types, the type of their difference, the type of the size of objects in
242
  this allocation model, as well as the memory allocation and deallocation
243
- primitives for it. All of the string types (Clause  [[strings]]),
244
- containers (Clause  [[containers]]) (except array), string buffers and
245
- string streams (Clause  [[input.output]]), and `match_results` (Clause 
246
- [[re]]) are parameterized in terms of allocators.
247
 
248
- The class template `allocator_traits` ([[allocator.traits]]) supplies a
249
- uniform interface to all allocator types. Table  [[tab:desc.var.def]]
250
- describes the types manipulated through allocators. Table 
251
- [[tab:utilities.allocator.requirements]] describes the requirements on
252
- allocator types and thus on types used to instantiate
253
- `allocator_traits`. A requirement is optional if the last column of
254
- Table  [[tab:utilities.allocator.requirements]] specifies a default for
255
- a given expression. Within the standard library `allocator_traits`
256
- template, an optional requirement that is not supplied by an allocator
257
- is replaced by the specified default expression. A user specialization
258
- of `allocator_traits` may provide different defaults and may provide
259
  defaults for different requirements than the primary template. Within
260
- Tables  [[tab:desc.var.def]] and 
261
- [[tab:utilities.allocator.requirements]], the use of `move` and
262
- `forward` always refers to `std::move` and `std::forward`, respectively.
263
 
264
  [*Note 1*: If `n == 0`, the return value is unspecified. — *end note*]
265
 
266
  Note A: The member class template `rebind` in the table above is
267
  effectively a typedef template.
@@ -277,29 +274,36 @@ and `Allocator` does not supply a `rebind` member template, the standard
277
  `allocator_traits` template uses `SomeAllocator<U, Args>` in place of
278
  `Allocator::{}rebind<U>::other` by default. For allocator types that are
279
  not template instantiations of the above form, no default is provided.
280
 
281
  Note B: If `X::propagate_on_container_copy_assignment::value` is `true`,
282
- `X` shall satisfy the `CopyAssignable` requirements (Table 
283
- [[tab:copyassignable]]) and the copy operation shall not throw
284
  exceptions. If `X::propagate_on_container_move_assignment::value` is
285
- `true`, `X` shall satisfy the `MoveAssignable` requirements (Table 
286
- [[tab:moveassignable]]) and the move operation shall not throw
287
  exceptions. If `X::propagate_on_container_swap::value` is `true`,
288
- lvalues of type `X` shall be swappable ([[swappable.requirements]]) and
289
  the `swap` operation shall not throw exceptions.
290
 
291
- An allocator type `X` shall satisfy the requirements of
292
- `CopyConstructible` ([[utility.arg.requirements]]). The `X::pointer`,
293
  `X::const_pointer`, `X::void_pointer`, and `X::const_void_pointer` types
294
- shall satisfy the requirements of `NullablePointer` (
295
- [[nullablepointer.requirements]]). No constructor, comparison function,
296
- copy operation, move operation, or swap operation on these pointer types
297
  shall exit via an exception. `X::pointer` and `X::const_pointer` shall
298
- also satisfy the requirements for a random access iterator (
299
- [[random.access.iterators]]) and of a contiguous iterator (
300
- [[iterator.requirements.general]]).
 
 
 
 
 
 
 
301
 
302
  Let `x1` and `x2` denote objects of (possibly different) types
303
  `X::void_pointer`, `X::const_void_pointer`, `X::pointer`, or
304
  `X::const_pointer`. Then, `x1` and `x2` are *equivalently-valued*
305
  pointer values, if and only if both `x1` and `x2` can be explicitly
@@ -338,25 +342,32 @@ An allocator may constrain the types on which it can be instantiated and
338
  the arguments for which its `construct` or `destroy` members may be
339
  called. If a type cannot be used with a particular allocator, the
340
  allocator class or the call to `construct` or `destroy` may fail to
341
  instantiate.
342
 
 
 
 
 
 
 
 
 
343
  [*Example 1*:
344
 
345
  The following is an allocator class template supporting the minimal
346
- interface that satisfies the requirements of Table 
347
- [[tab:utilities.allocator.requirements]]:
348
 
349
  ``` cpp
350
  template<class Tp>
351
  struct SimpleAllocator {
352
  typedef Tp value_type;
353
  SimpleAllocator(ctor args);
354
 
355
  template<class T> SimpleAllocator(const SimpleAllocator<T>& other);
356
 
357
- Tp* allocate(std::size_t n);
358
  void deallocate(Tp* p, std::size_t n);
359
  };
360
 
361
  template<class T, class U>
362
  bool operator==(const SimpleAllocator<T>&, const SimpleAllocator<U>&);
@@ -364,23 +375,15 @@ template <class T, class U>
364
  bool operator!=(const SimpleAllocator<T>&, const SimpleAllocator<U>&);
365
  ```
366
 
367
  — *end example*]
368
 
369
- If the alignment associated with a specific over-aligned type is not
370
- supported by an allocator, instantiation of the allocator for that type
371
- may fail. The allocator also may silently ignore the requested
372
- alignment.
373
-
374
- [*Note 3*: Additionally, the member function `allocate` for that type
375
- may fail by throwing an object of type `bad_alloc`. — *end note*]
376
-
377
  ##### Allocator completeness requirements <a id="allocator.requirements.completeness">[[allocator.requirements.completeness]]</a>
378
 
379
- If `X` is an allocator class for type `T`, `X` additionally satisfies
380
- the allocator completeness requirements if, whether or not `T` is a
381
- complete type:
382
 
383
  - `X` is a complete type, and
384
- - all the member types of `allocator_traits<X>` ([[allocator.traits]])
385
  other than `value_type` are complete types.
386
 
 
12
 
13
  #### Template argument requirements <a id="utility.arg.requirements">[[utility.arg.requirements]]</a>
14
 
15
  The template definitions in the C++ standard library refer to various
16
  named requirements whose details are set out in Tables 
17
+ [[tab:cpp17.equalitycomparable]]– [[tab:cpp17.destructible]]. In these
18
+ tables, `T` is an object or reference type to be supplied by a C++
19
+ program instantiating a template; `a`, `b`, and `c` are values of type
20
+ (possibly `const`) `T`; `s` and `t` are modifiable lvalues of type `T`;
21
+ `u` denotes an identifier; `rv` is an rvalue of type `T`; and `v` is an
22
  lvalue of type (possibly `const`) `T` or an rvalue of type `const T`.
23
 
24
  In general, a default constructor is not required. Certain container
25
  class member function signatures specify `T()` as a default argument.
26
+ `T()` shall be a well-defined expression [[dcl.init]] if one of those
27
+ signatures is called using the default argument [[dcl.fct.default]].
28
 
29
+ **Table: Cpp17EqualityComparable requirements** <a id="cpp17.equalitycomparable">[cpp17.equalitycomparable]</a>
30
 
31
  | Expression | Return type |
32
  | ---------- | ----------- |
33
  | `a == b` | convertible to `bool` | `==` is an equivalence relation, that is, it has the following properties: For all `a`, `a == a`.; If `a == b`, then `b == a`.; If `a == b` and `b == c`, then `a == c`. |
34
 
35
+
36
+ **Table: Cpp17LessThanComparable requirements** <a id="cpp17.lessthancomparable">[cpp17.lessthancomparable]</a>
37
 
38
  | Expression | Return type | Requirement |
39
+ | ---------- | --------------------- | ------------------------------------------------------ |
40
+ | `a < b` | convertible to `bool` | `<` is a strict weak ordering relation [[alg.sorting]] |
41
 
42
+
43
+ **Table: Cpp17DefaultConstructible requirements** <a id="cpp17.defaultconstructible">[cpp17.defaultconstructible]</a>
44
 
45
  | Expression | Post-condition |
46
  | -------------- | ------------------------------------------------------------------- |
47
  | `T t;` | object `t` is default-initialized |
48
  | `T u{};` | object `u` is value-initialized or aggregate-initialized |
49
  | `T()`<br>`T{}` | an object of type `T` is value-initialized or aggregate-initialized |
50
 
51
+
52
  [*Note 1*: `rv` must still meet the requirements of the library
53
  component that is using it. The operations listed in those requirements
54
  must work as specified whether `rv` has been moved from or
55
  not. — *end note*]
56
 
57
+ **Table: Cpp17CopyConstructible requirements (in addition to Cpp17MoveConstructible)** <a id="cpp17.copyconstructible">[cpp17.copyconstructible]</a>
58
 
59
  | Expression | Post-condition |
60
  | ---------- | --------------------------------------------------------- |
61
  | `T u = v;` | the value of `v` is unchanged and is equivalent to ` u` |
62
  | `T(v)` | the value of `v` is unchanged and is equivalent to `T(v)` |
63
 
64
+
65
  [*Note 2*:  `rv` must still meet the requirements of the library
66
  component that is using it, whether or not `t` and `rv` refer to the
67
  same object. The operations listed in those requirements must work as
68
  specified whether `rv` has been moved from or not. — *end note*]
69
 
70
+ **Table: Cpp17CopyAssignable requirements (in addition to Cpp17MoveAssignable)** <a id="cpp17.copyassignable">[cpp17.copyassignable]</a>
71
 
72
  | Expression | Return type | Return value | Post-condition |
73
  | ---------- | ----------- | ------------ | ------------------------------------------------------- |
74
  | `t = v` | `T&` | `t` | `t` is equivalent to `v`, the value of `v` is unchanged |
75
 
76
 
77
+ [*Note 3*: Array types and non-object types are not
78
+ *Cpp17Destructible*. — *end note*]
79
 
80
+ #### Swappable requirements <a id="swappable.requirements">[[swappable.requirements]]</a>
 
 
 
 
 
81
 
82
  This subclause provides definitions for swappable types and expressions.
83
  In these definitions, let `t` denote an expression of type `T`, and let
84
  `u` denote an expression of type `U`.
85
 
 
92
  and
93
  - the object referred to by `u` has the value originally held by `t`.
94
 
95
  The context in which `swap(t, u)` and `swap(u, t)` are evaluated shall
96
  ensure that a binary non-member function named “swap” is selected via
97
+ overload resolution [[over.match]] on a candidate set that includes:
98
 
99
+ - the two `swap` function templates defined in `<utility>` and
100
+ - the lookup set produced by argument-dependent lookup
101
+ [[basic.lookup.argdep]].
 
102
 
103
  [*Note 1*: If `T` and `U` are both fundamental types or arrays of
104
  fundamental types and the declarations from the header `<utility>` are
105
  in scope, the overall lookup set described above is equivalent to that
106
  of the qualified name lookup applied to the expression `std::swap(t, u)`
 
111
  appropriate evaluation context. — *end note*]
112
 
113
  An rvalue or lvalue `t` is *swappable* if and only if `t` is swappable
114
  with any rvalue or lvalue, respectively, of type `T`.
115
 
116
+ A type `X` meeting any of the iterator requirements
117
+ [[iterator.requirements]] meets the *Cpp17ValueSwappable* requirements
118
+ if, for any dereferenceable object `x` of type `X`, `*x` is swappable.
 
119
 
120
  [*Example 1*:
121
 
122
  User code can ensure that the evaluation of `swap` calls is performed in
123
  an appropriate context under the various conditions as follows:
 
135
 
136
  // Requires: lvalues of T shall be swappable.
137
  template<class T>
138
  void lv_swap(T& t1, T& t2) {
139
  using std::swap;
140
+ swap(t1, t2); // OK: uses swappable conditions for lvalues of type T
141
+ }
142
 
143
  namespace N {
144
  struct A { int m; };
145
  struct Proxy { A* a; };
146
  Proxy proxy(A& a) { return Proxy{ &a }; }
 
163
  }
164
  ```
165
 
166
  — *end example*]
167
 
168
+ #### *Cpp17NullablePointer* requirements <a id="nullablepointer.requirements">[[nullablepointer.requirements]]</a>
169
 
170
+ A *Cpp17NullablePointer* type is a pointer-like type that supports null
171
+ values. A type `P` meets the *Cpp17NullablePointer* requirements if:
172
 
173
+ - `P` meets the *Cpp17EqualityComparable*, *Cpp17DefaultConstructible*,
174
+ *Cpp17CopyConstructible*, *Cpp17CopyAssignable*, and
175
+ *Cpp17Destructible* requirements,
176
+ - lvalues of type `P` are swappable [[swappable.requirements]],
177
+ - the expressions shown in [[cpp17.nullablepointer]] are valid and have
178
+ the indicated semantics, and
179
+ - `P` meets all the other requirements of this subclause.
180
 
181
  A value-initialized object of type `P` produces the null value of the
182
  type. The null value shall be equivalent only to itself. A
183
  default-initialized object of type `P` may have an indeterminate value.
184
 
185
  [*Note 1*: Operations involving indeterminate values may cause
186
  undefined behavior. — *end note*]
187
 
188
  An object `p` of type `P` can be contextually converted to `bool`
189
+ [[conv]]. The effect shall be as if `p != nullptr` had been evaluated in
190
+ place of `p`.
191
 
192
+ No operation which is part of the *Cpp17NullablePointer* requirements
193
+ shall exit via an exception.
194
 
195
+ In [[cpp17.nullablepointer]], `u` denotes an identifier, `t` denotes a
196
+ non-`const` lvalue of type `P`, `a` and `b` denote values of type
197
+ (possibly `const`) `P`, and `np` denotes a value of type (possibly
198
  `const`) `std::nullptr_t`.
199
 
200
+ **Table: Cpp17NullablePointer requirements** <a id="cpp17.nullablepointer">[cpp17.nullablepointer]</a>
201
 
202
+ | Expression | Return type | Operational semantics |
203
+ | -------------- | ---------------------------------- | --------------------------- |
204
+ | `P u(np);`<br> | | Ensures: `u == nullptr` |
205
  | `P u = np;` | | |
206
+ | `P(np)` | | Ensures: `P(np) == nullptr` |
207
+ | `t = np` | `P&` | Ensures: `t == nullptr` |
208
  | `a != b` | contextually convertible to `bool` | `!(a == b)` |
209
  | `a == np` | contextually convertible to `bool` | `a == P()` |
210
  | `np == a` | | |
211
  | `a != np` | contextually convertible to `bool` | `!(a == np)` |
212
  | `np != a` | | |
213
 
214
 
215
+ #### *Cpp17Hash* requirements <a id="hash.requirements">[[hash.requirements]]</a>
216
 
217
+ A type `H` meets the requirements if:
218
 
219
+ - it is a function object type [[function.objects]],
220
+ - it meets the *Cpp17CopyConstructible* ([[cpp17.copyconstructible]])
221
+ and *Cpp17Destructible* ([[cpp17.destructible]]) requirements, and
222
+ - the expressions shown in [[cpp17.hash]] are valid and have the
223
  indicated semantics.
224
 
225
  Given `Key` is an argument type for function objects of type `H`, in
226
+ [[cpp17.hash]] `h` is a value of type (possibly `const`) `H`, `u` is an
227
+ lvalue of type `Key`, and `k` is a value of a type convertible to
228
  (possibly `const`) `Key`.
229
 
230
  [*Note 1*: Thus all evaluations of the expression `h(k)` with the same
231
  value for `k` yield the same result for a given execution of the
232
  program. — *end note*]
233
 
234
+ #### *Cpp17Allocator* requirements <a id="allocator.requirements">[[allocator.requirements]]</a>
235
 
236
  The library describes a standard set of requirements for *allocators*,
237
  which are class-type objects that encapsulate the information about an
238
  allocation model. This information includes the knowledge of pointer
239
  types, the type of their difference, the type of the size of objects in
240
  this allocation model, as well as the memory allocation and deallocation
241
+ primitives for it. All of the string types [[strings]], containers
242
+ [[containers]] (except `array`), string buffers and string streams
243
+ [[input.output]], and `match_results` [[re]] are parameterized in terms
244
+ of allocators.
245
 
246
+ The class template `allocator_traits` [[allocator.traits]] supplies a
247
+ uniform interface to all allocator types. [[allocator.req.var]]
248
+ describes the types manipulated through allocators. [[cpp17.allocator]]
249
+ describes the requirements on allocator types and thus on types used to
250
+ instantiate `allocator_traits`. A requirement is optional if the last
251
+ column of [[cpp17.allocator]] specifies a default for a given
252
+ expression. Within the standard library `allocator_traits` template, an
253
+ optional requirement that is not supplied by an allocator is replaced by
254
+ the specified default expression. A user specialization of
255
+ `allocator_traits` may provide different defaults and may provide
 
256
  defaults for different requirements than the primary template. Within
257
+ Tables  [[tab:allocator.req.var]] and  [[tab:cpp17.allocator]], the use
258
+ of `move` and `forward` always refers to `std::move` and `std::forward`,
259
+ respectively.
260
 
261
  [*Note 1*: If `n == 0`, the return value is unspecified. — *end note*]
262
 
263
  Note A: The member class template `rebind` in the table above is
264
  effectively a typedef template.
 
274
  `allocator_traits` template uses `SomeAllocator<U, Args>` in place of
275
  `Allocator::{}rebind<U>::other` by default. For allocator types that are
276
  not template instantiations of the above form, no default is provided.
277
 
278
  Note B: If `X::propagate_on_container_copy_assignment::value` is `true`,
279
+ `X` shall meet the *Cpp17CopyAssignable* requirements (
280
+ [[cpp17.copyassignable]]) and the copy operation shall not throw
281
  exceptions. If `X::propagate_on_container_move_assignment::value` is
282
+ `true`, `X` shall meet the *Cpp17MoveAssignable* requirements (
283
+ [[cpp17.moveassignable]]) and the move operation shall not throw
284
  exceptions. If `X::propagate_on_container_swap::value` is `true`,
285
+ lvalues of type `X` shall be swappable [[swappable.requirements]] and
286
  the `swap` operation shall not throw exceptions.
287
 
288
+ An allocator type `X` shall meet the *Cpp17CopyConstructible*
289
+ requirements ([[cpp17.copyconstructible]]). The `X::pointer`,
290
  `X::const_pointer`, `X::void_pointer`, and `X::const_void_pointer` types
291
+ shall meet the *Cpp17NullablePointer* requirements (
292
+ [[cpp17.nullablepointer]]). No constructor, comparison function, copy
293
+ operation, move operation, or swap operation on these pointer types
294
  shall exit via an exception. `X::pointer` and `X::const_pointer` shall
295
+ also meet the requirements for a *Cpp17RandomAccessIterator*
296
+ [[random.access.iterators]] and the additional requirement that, when
297
+ `a` and `(a + n)` are dereferenceable pointer values for some integral
298
+ value `n`,
299
+
300
+ ``` cpp
301
+ addressof(*(a + n)) == addressof(*a) + n
302
+ ```
303
+
304
+ is `true`.
305
 
306
  Let `x1` and `x2` denote objects of (possibly different) types
307
  `X::void_pointer`, `X::const_void_pointer`, `X::pointer`, or
308
  `X::const_pointer`. Then, `x1` and `x2` are *equivalently-valued*
309
  pointer values, if and only if both `x1` and `x2` can be explicitly
 
342
  the arguments for which its `construct` or `destroy` members may be
343
  called. If a type cannot be used with a particular allocator, the
344
  allocator class or the call to `construct` or `destroy` may fail to
345
  instantiate.
346
 
347
+ If the alignment associated with a specific over-aligned type is not
348
+ supported by an allocator, instantiation of the allocator for that type
349
+ may fail. The allocator also may silently ignore the requested
350
+ alignment.
351
+
352
+ [*Note 3*: Additionally, the member function `allocate` for that type
353
+ may fail by throwing an object of type `bad_alloc`. — *end note*]
354
+
355
  [*Example 1*:
356
 
357
  The following is an allocator class template supporting the minimal
358
+ interface that meets the requirements of [[cpp17.allocator]]:
 
359
 
360
  ``` cpp
361
  template<class Tp>
362
  struct SimpleAllocator {
363
  typedef Tp value_type;
364
  SimpleAllocator(ctor args);
365
 
366
  template<class T> SimpleAllocator(const SimpleAllocator<T>& other);
367
 
368
+ [[nodiscard]] Tp* allocate(std::size_t n);
369
  void deallocate(Tp* p, std::size_t n);
370
  };
371
 
372
  template<class T, class U>
373
  bool operator==(const SimpleAllocator<T>&, const SimpleAllocator<U>&);
 
375
  bool operator!=(const SimpleAllocator<T>&, const SimpleAllocator<U>&);
376
  ```
377
 
378
  — *end example*]
379
 
 
 
 
 
 
 
 
 
380
  ##### Allocator completeness requirements <a id="allocator.requirements.completeness">[[allocator.requirements.completeness]]</a>
381
 
382
+ If `X` is an allocator class for type `T`, `X` additionally meets the
383
+ allocator completeness requirements if, whether or not `T` is a complete
384
+ type:
385
 
386
  - `X` is a complete type, and
387
+ - all the member types of `allocator_traits<X>` [[allocator.traits]]
388
  other than `value_type` are complete types.
389