[utility.requirements] - C++20 → C++23

Files changed (1) hide show

tmp/tmpa68jsqso/{from.md → to.md} +491 -101

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

@@ -1,7 +1,9 @@
 ### Requirements on types and expressions <a id="utility.requirements">[[utility.requirements]]</a>
 [[utility.arg.requirements]] describes requirements on types and
 expressions used to instantiate templates defined in the C++ standard
 library. [[swappable.requirements]] describes the requirements on
 swappable types and swappable expressions.
 [[nullablepointer.requirements]] describes the requirements on
@@ -13,33 +15,38 @@ allocators.
 #### Template argument requirements <a id="utility.arg.requirements">[[utility.arg.requirements]]</a>
 The template definitions in the C++ standard library refer to various
 named requirements whose details are set out in Tables
 [[tab:cpp17.equalitycomparable]]– [[tab:cpp17.destructible]]. In these
-tables, `T` is an object or reference type to be supplied by a C++
-program instantiating a template; `a`, `b`, and `c` are values of type
-(possibly `const`) `T`; `s` and `t` are modifiable lvalues of type `T`;
-`u` denotes an identifier; `rv` is an rvalue of type `T`; and `v` is an
-lvalue of type (possibly `const`) `T` or an rvalue of type `const T`.
 In general, a default constructor is not required. Certain container
 class member function signatures specify `T()` as a default argument.
 `T()` shall be a well-defined expression [[dcl.init]] if one of those
 signatures is called using the default argument [[dcl.fct.default]].
 **Table: Cpp17EqualityComparable requirements** <a id="cpp17.equalitycomparable">[cpp17.equalitycomparable]</a>
 | Expression | Return type |
 | ---------- | ----------- |
-| `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`. |
 **Table: Cpp17LessThanComparable requirements** <a id="cpp17.lessthancomparable">[cpp17.lessthancomparable]</a>
 | Expression | Return type                                 | Requirement                                            |
-| ---------- | --------------------- | ------------------------------------------------------ |
-| `a < b`    | convertible to `bool` | `<` is a strict weak ordering relation [[alg.sorting]] |
 **Table: Cpp17DefaultConstructible requirements** <a id="cpp17.defaultconstructible">[cpp17.defaultconstructible]</a>
 | Expression     | Post-condition                                                      |
@@ -47,37 +54,49 @@ signatures is called using the default argument [[dcl.fct.default]].
 | `T t;`         | object `t` is default-initialized                                   |
 | `T u{};`       | object `u` is value-initialized or aggregate-initialized            |
 | `T()`<br>`T{}` | an object of type `T` is value-initialized or aggregate-initialized |
-[*Note 1*: `rv` must still meet the requirements of the library
-component that is using it. The operations listed in those requirements
-must work as specified whether `rv` has been moved from or
-not. — *end note*]
 **Table: Cpp17CopyConstructible requirements (in addition to Cpp17MoveConstructible)** <a id="cpp17.copyconstructible">[cpp17.copyconstructible]</a>
 | Expression | Post-condition                                            |
 | ---------- | --------------------------------------------------------- |
 | `T u = v;` | the value of `v` is unchanged and is equivalent to ` u`   |
 | `T(v)`     | the value of `v` is unchanged and is equivalent to `T(v)` |
-[*Note 2*:  `rv` must still meet the requirements of the library
-component that is using it, whether or not `t` and `rv` refer to the
-same object. The operations listed in those requirements must work as
-specified whether `rv` has been moved from or not. — *end note*]
 **Table: Cpp17CopyAssignable requirements (in addition to Cpp17MoveAssignable)** <a id="cpp17.copyassignable">[cpp17.copyassignable]</a>
 | Expression | Return type | Return value | Post-condition                                          |
 | ---------- | ----------- | ------------ | ------------------------------------------------------- |
 | `t = v`    | `T&`        | `t`          | `t` is equivalent to `v`, the value of `v` is unchanged |
-[*Note 3*: Array types and non-object types are not
-*Cpp17Destructible*. — *end note*]
 #### Swappable requirements <a id="swappable.requirements">[[swappable.requirements]]</a>
 This subclause provides definitions for swappable types and expressions.
 In these definitions, let `t` denote an expression of type `T`, and let
@@ -111,44 +130,48 @@ swappable requirement includes the header `<utility>` to ensure an
 appropriate evaluation context. — *end note*]
 An rvalue or lvalue `t` is *swappable* if and only if `t` is swappable
 with any rvalue or lvalue, respectively, of type `T`.
 A type `X` meeting any of the iterator requirements
 [[iterator.requirements]] meets the *Cpp17ValueSwappable* requirements
 if, for any dereferenceable object `x` of type `X`, `*x` is swappable.
 [*Example 1*:
 User code can ensure that the evaluation of `swap` calls is performed in
 an appropriate context under the various conditions as follows:
 ``` cpp
 #include <utility>
-// Requires: std::forward<T>(t) shall be swappable with std::forward<U>(u).
 template<class T, class U>
 void value_swap(T&& t, U&& u) {
   using std::swap;
-  swap(std::forward<T>(t), std::forward<U>(u)); // OK: uses ``swappable with'' conditions
                                                 // for rvalues and lvalues
 }
-// Requires: lvalues of T shall be swappable.
 template<class T>
 void lv_swap(T& t1, T& t2) {
   using std::swap;
-  swap(t1, t2);                                 // OK: uses swappable conditions for lvalues of type T
 }
 namespace N {
   struct A { int m; };
   struct Proxy { A* a; };
   Proxy proxy(A& a) { return Proxy{ &a }; }
   void swap(A& x, Proxy p) {
-    std::swap(x.m, p.a->m);                     // OK: uses context equivalent to swappable
                                                 // conditions for fundamental types
   }
   void swap(Proxy p, A& x) { swap(x, p); }      // satisfy symmetry constraint
 }
@@ -169,22 +192,21 @@ int main() {
 A *Cpp17NullablePointer* type is a pointer-like type that supports null
 values. A type `P` meets the *Cpp17NullablePointer* requirements if:
 - `P` meets the *Cpp17EqualityComparable*, *Cpp17DefaultConstructible*,
-  *Cpp17CopyConstructible*, *Cpp17CopyAssignable*, and
   *Cpp17Destructible* requirements,
-- lvalues of type `P` are swappable [[swappable.requirements]],
 - the expressions shown in [[cpp17.nullablepointer]] are valid and have
   the indicated semantics, and
 - `P` meets all the other requirements of this subclause.
 A value-initialized object of type `P` produces the null value of the
 type. The null value shall be equivalent only to itself. A
 default-initialized object of type `P` may have an indeterminate value.
-[*Note 1*: Operations involving indeterminate values may cause
 undefined behavior. — *end note*]
 An object `p` of type `P` can be contextually converted to `bool`
 [[conv]]. The effect shall be as if `p != nullptr` had been evaluated in
 place of `p`.
@@ -192,25 +214,25 @@ place of `p`.
 No operation which is part of the *Cpp17NullablePointer* requirements
 shall exit via an exception.
 In [[cpp17.nullablepointer]], `u` denotes an identifier, `t` denotes a
 non-`const` lvalue of type `P`, `a` and `b` denote values of type
-(possibly `const`) `P`, and `np` denotes a value of type (possibly
-`const`) `std::nullptr_t`.
 **Table: Cpp17NullablePointer requirements** <a id="cpp17.nullablepointer">[cpp17.nullablepointer]</a>
 | Expression     | Return type                                                               | Operational semantics       |
-| -------------- | ---------------------------------- | --------------------------- |
 | `P u(np);`<br> |                                                                           | Ensures: `u == nullptr`     |
 | `P u = np;`    |                                                                           |                             |
 | `P(np)`        |                                                                           | Ensures: `P(np) == nullptr` |
 | `t = np`       | `P&`                                                                      | Ensures: `t == nullptr`     |
-| `a != b`       | contextually convertible to `bool` | `!(a == b)`                 |
-| `a == np`      | contextually convertible to `bool` | `a == P()`                  |
 | `np == a`      |                                                                           |                             |
-| `a != np`      | contextually convertible to `bool` | `!(a == np)`                |
 | `np != a`      |                                                                           |                             |
 #### *Cpp17Hash* requirements <a id="hash.requirements">[[hash.requirements]]</a>
@@ -221,110 +243,480 @@ A type `H` meets the requirements if:
   and *Cpp17Destructible* ([[cpp17.destructible]]) requirements, and
 - the expressions shown in [[cpp17.hash]] are valid and have the
   indicated semantics.
 Given `Key` is an argument type for function objects of type `H`, in
-[[cpp17.hash]] `h` is a value of type (possibly `const`) `H`, `u` is an
 lvalue of type `Key`, and `k` is a value of a type convertible to
-(possibly `const`) `Key`.
 [*Note 1*: Thus all evaluations of the expression `h(k)` with the same
 value for `k` yield the same result for a given execution of the
 program. — *end note*]
 #### *Cpp17Allocator* requirements <a id="allocator.requirements">[[allocator.requirements]]</a>
 The library describes a standard set of requirements for *allocators*,
 which are class-type objects that encapsulate the information about an
 allocation model. This information includes the knowledge of pointer
 types, the type of their difference, the type of the size of objects in
 this allocation model, as well as the memory allocation and deallocation
 primitives for it. All of the string types [[strings]], containers
 [[containers]] (except `array`), string buffers and string streams
 [[input.output]], and `match_results` [[re]] are parameterized in terms
 of allocators.
 The class template `allocator_traits` [[allocator.traits]] supplies a
-uniform interface to all allocator types. [[allocator.req.var]]
-describes the types manipulated through allocators. [[cpp17.allocator]]
-describes the requirements on allocator types and thus on types used to
-instantiate `allocator_traits`. A requirement is optional if the last
-column of [[cpp17.allocator]] specifies a default for a given
-expression. Within the standard library `allocator_traits` template, an
-optional requirement that is not supplied by an allocator is replaced by
-the specified default expression. A user specialization of
-`allocator_traits` may provide different defaults and may provide
-defaults for different requirements than the primary template. Within
-Tables  [[tab:allocator.req.var]] and  [[tab:cpp17.allocator]], the use
-of `move` and `forward` always refers to `std::move` and `std::forward`,
-respectively.
-[*Note 1*: If `n == 0`, the return value is unspecified. — *end note*]
-Note A: The member class template `rebind` in the table above is
-effectively a typedef template.
-[*Note 2*: In general, if the name `Allocator` is bound to
-`SomeAllocator<T>`, then `Allocator::rebind<U>::other` is the same type
-as `SomeAllocator<U>`, where `SomeAllocator<T>::value_type` is `T` and
-`SomeAllocator<U>::{}value_type` is `U`. — *end note*]
-If `Allocator` is a class template instantiation of the form
 `SomeAllocator<T, Args>`, where `Args` is zero or more type arguments,
 and `Allocator` does not supply a `rebind` member template, the standard
 `allocator_traits` template uses `SomeAllocator<U, Args>` in place of
-`Allocator::{}rebind<U>::other` by default. For allocator types that are
 not template instantiations of the above form, no default is provided.
-Note B: If `X::propagate_on_container_copy_assignment::value` is `true`,
-`X` shall meet the *Cpp17CopyAssignable* requirements (
-[[cpp17.copyassignable]]) and the copy operation shall not throw
-exceptions. If `X::propagate_on_container_move_assignment::value` is
-`true`, `X` shall meet the *Cpp17MoveAssignable* requirements (
-[[cpp17.moveassignable]]) and the move operation shall not throw
-exceptions. If `X::propagate_on_container_swap::value` is `true`,
-lvalues of type `X` shall be swappable [[swappable.requirements]] and
-the `swap` operation shall not throw exceptions.
 An allocator type `X` shall meet the *Cpp17CopyConstructible*
-requirements ([[cpp17.copyconstructible]]). The `X::pointer`,
-`X::const_pointer`, `X::void_pointer`, and `X::const_void_pointer` types
-shall meet the *Cpp17NullablePointer* requirements (
-[[cpp17.nullablepointer]]). No constructor, comparison function, copy
-operation, move operation, or swap operation on these pointer types
-shall exit via an exception. `X::pointer` and `X::const_pointer` shall
-also meet the requirements for a *Cpp17RandomAccessIterator*
-[[random.access.iterators]] and the additional requirement that, when
-`a` and `(a + n)` are dereferenceable pointer values for some integral
-value `n`,
 ``` cpp
-addressof(*(a + n)) == addressof(*a) + n
 ```
 is `true`.
 Let `x1` and `x2` denote objects of (possibly different) types
-`X::void_pointer`, `X::const_void_pointer`, `X::pointer`, or
-`X::const_pointer`. Then, `x1` and `x2` are *equivalently-valued*
 pointer values, if and only if both `x1` and `x2` can be explicitly
 converted to the two corresponding objects `px1` and `px2` of type
-`X::const_pointer`, using a sequence of `static_cast`s using only these
 four types, and the expression `px1 == px2` evaluates to `true`.
-Let `w1` and `w2` denote objects of type `X::void_pointer`. Then for the
-expressions
 ``` cpp
 w1 == w2
 w1 != w2
 ```
 either or both objects may be replaced by an equivalently-valued object
-of type `X::const_void_pointer` with no change in semantics.
-Let `p1` and `p2` denote objects of type `X::pointer`. Then for the
 expressions
 ``` cpp
 p1 == p2
 p1 != p2
@@ -334,11 +726,11 @@ p1 >= p2
 p1 > p2
 p1 - p2
 ```
 either or both objects may be replaced by an equivalently-valued object
-of type `X::const_pointer` with no change in semantics.
 An allocator may constrain the types on which it can be instantiated and
 the arguments for which its `construct` or `destroy` members may be
 called. If a type cannot be used with a particular allocator, the
 allocator class or the call to `construct` or `destroy` may fail to
@@ -347,34 +739,32 @@ instantiate.
 If the alignment associated with a specific over-aligned type is not
 supported by an allocator, instantiation of the allocator for that type
 may fail. The allocator also may silently ignore the requested
 alignment.
-[*Note 3*: Additionally, the member function `allocate` for that type
-may fail by throwing an object of type `bad_alloc`. — *end note*]
 [*Example 1*:
 The following is an allocator class template supporting the minimal
-interface that meets the requirements of [[cpp17.allocator]]:
 ``` cpp
-template<class Tp>
 struct SimpleAllocator {
- typedef Tp value_type;
   SimpleAllocator(ctor args);
-  template<class T> SimpleAllocator(const SimpleAllocator<T>& other);
- [[nodiscard]] Tp* allocate(std::size_t n);
-  void deallocate(Tp* p, std::size_t n);
 };
-template<class T, class U>
-bool operator==(const SimpleAllocator<T>&, const SimpleAllocator<U>&);
-template<class T, class U>
-bool operator!=(const SimpleAllocator<T>&, const SimpleAllocator<U>&);
 ```
 — *end example*]
 ##### Allocator completeness requirements <a id="allocator.requirements.completeness">[[allocator.requirements.completeness]]</a>

 ### Requirements on types and expressions <a id="utility.requirements">[[utility.requirements]]</a>
+#### General <a id="utility.requirements.general">[[utility.requirements.general]]</a>
 [[utility.arg.requirements]] describes requirements on types and
 expressions used to instantiate templates defined in the C++ standard
 library. [[swappable.requirements]] describes the requirements on
 swappable types and swappable expressions.
 [[nullablepointer.requirements]] describes the requirements on
 #### Template argument requirements <a id="utility.arg.requirements">[[utility.arg.requirements]]</a>
 The template definitions in the C++ standard library refer to various
 named requirements whose details are set out in Tables
 [[tab:cpp17.equalitycomparable]]– [[tab:cpp17.destructible]]. In these
+tables,
+- `T` denotes an object or reference type to be supplied by a C++
+  program instantiating a template,
+- `a`, `b`, and `c` denote values of type (possibly const) `T`,
+- `s` and `t` denote modifiable lvalues of type `T`,
+- `u` denotes an identifier,
+- `rv` denotes an rvalue of type `T`, and
+- `v` denotes an lvalue of type (possibly const) `T` or an rvalue of
+  type `const T`.
 In general, a default constructor is not required. Certain container
 class member function signatures specify `T()` as a default argument.
 `T()` shall be a well-defined expression [[dcl.init]] if one of those
 signatures is called using the default argument [[dcl.fct.default]].
 **Table: Cpp17EqualityComparable requirements** <a id="cpp17.equalitycomparable">[cpp17.equalitycomparable]</a>
 | Expression | Return type |
 | ---------- | ----------- |
+| `a == b`   | `decltype(a == b)` models `boolean-testable` | `==` 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`. |
 **Table: Cpp17LessThanComparable requirements** <a id="cpp17.lessthancomparable">[cpp17.lessthancomparable]</a>
 | Expression | Return type                                 | Requirement                                            |
+| ---------- | ------------------------------------------- | ------------------------------------------------------ |
+| `a < b`    | `decltype(a < b)` models `boolean-testable` | `<` is a strict weak ordering relation [[alg.sorting]] |
 **Table: Cpp17DefaultConstructible requirements** <a id="cpp17.defaultconstructible">[cpp17.defaultconstructible]</a>
 | Expression     | Post-condition                                                      |
 | `T t;`         | object `t` is default-initialized                                   |
 | `T u{};`       | object `u` is value-initialized or aggregate-initialized            |
 | `T()`<br>`T{}` | an object of type `T` is value-initialized or aggregate-initialized |
+**Table: Cpp17MoveConstructible requirements** <a id="cpp17.moveconstructible">[cpp17.moveconstructible]</a>
+| Expression  | Post-condition                                                     |
+| ----------- | ------------------------------------------------------------------ |
+| `T u = rv;` | `u` is equivalent to the value of `rv` before the construction     |
+| `T(rv)`     | `T(rv)` is equivalent to the value of `rv` before the construction |
+| *[spans 2 columns]*  `rv`'s state is unspecified *`rv` must still meet the requirements of the library component that is using it. The operations listed in those requirements must work as specified whether `rv` has been moved from or not.* |
 **Table: Cpp17CopyConstructible requirements (in addition to Cpp17MoveConstructible)** <a id="cpp17.copyconstructible">[cpp17.copyconstructible]</a>
 | Expression | Post-condition                                            |
 | ---------- | --------------------------------------------------------- |
 | `T u = v;` | the value of `v` is unchanged and is equivalent to ` u`   |
 | `T(v)`     | the value of `v` is unchanged and is equivalent to `T(v)` |
+**Table: Cpp17MoveAssignable requirements** <a id="cpp17.moveassignable">[cpp17.moveassignable]</a>
+| Expression | Return type | Return value | Post-condition                                                                                                |
+| ---------- | ----------- | ------------ | ------------------------------------------------------------------------------------------------------------- |
+| `t = rv`   | `T&`        | `t`          | If `t` and `rv` do not refer to the same object, `t` is equivalent to the value of `rv` before the assignment |
+| *[spans 4 columns]*  `rv`'s state is unspecified. *`rv` must still meet the requirements of the library component that is using it, whether or not `t` and `rv` refer to the same object. The operations listed in those requirements must work as specified whether `rv` has been moved from or not.* |
 **Table: Cpp17CopyAssignable requirements (in addition to Cpp17MoveAssignable)** <a id="cpp17.copyassignable">[cpp17.copyassignable]</a>
 | Expression | Return type | Return value | Post-condition                                          |
 | ---------- | ----------- | ------------ | ------------------------------------------------------- |
 | `t = v`    | `T&`        | `t`          | `t` is equivalent to `v`, the value of `v` is unchanged |
+**Table: Cpp17Destructible requirements** <a id="cpp17.destructible">[cpp17.destructible]</a>
+| Expression | Post-condition                                                        |
+| ---------- | --------------------------------------------------------------------- |
+| `u.~T()`   | All resources owned by `u` are reclaimed, no exception is propagated. |
+| *[spans 2 columns]*  *Array types and non-object types are not Cpp17Destructible.* |
 #### Swappable requirements <a id="swappable.requirements">[[swappable.requirements]]</a>
 This subclause provides definitions for swappable types and expressions.
 In these definitions, let `t` denote an expression of type `T`, and let
 appropriate evaluation context. — *end note*]
 An rvalue or lvalue `t` is *swappable* if and only if `t` is swappable
 with any rvalue or lvalue, respectively, of type `T`.
+A type `X` meets the *Cpp17Swappable* requirements if lvalues of type
+`X` are swappable.
 A type `X` meeting any of the iterator requirements
 [[iterator.requirements]] meets the *Cpp17ValueSwappable* requirements
 if, for any dereferenceable object `x` of type `X`, `*x` is swappable.
 [*Example 1*:
 User code can ensure that the evaluation of `swap` calls is performed in
 an appropriate context under the various conditions as follows:
 ``` cpp
+#include <cassert>
 #include <utility>
+// Preconditions: std::forward<T>(t) is swappable with std::forward<U>(u).
 template<class T, class U>
 void value_swap(T&& t, U&& u) {
   using std::swap;
+  swap(std::forward<T>(t), std::forward<U>(u)); // OK, uses ``swappable with'' conditions
                                                 // for rvalues and lvalues
 }
+// Preconditions: T meets the Cpp17Swappable requirements.
 template<class T>
 void lv_swap(T& t1, T& t2) {
   using std::swap;
+  swap(t1, t2);                                 // OK, uses swappable conditions for lvalues of type T
 }
 namespace N {
   struct A { int m; };
   struct Proxy { A* a; };
   Proxy proxy(A& a) { return Proxy{ &a }; }
   void swap(A& x, Proxy p) {
+    std::swap(x.m, p.a->m);                     // OK, uses context equivalent to swappable
                                                 // conditions for fundamental types
   }
   void swap(Proxy p, A& x) { swap(x, p); }      // satisfy symmetry constraint
 }
 A *Cpp17NullablePointer* type is a pointer-like type that supports null
 values. A type `P` meets the *Cpp17NullablePointer* requirements if:
 - `P` meets the *Cpp17EqualityComparable*, *Cpp17DefaultConstructible*,
+  *Cpp17CopyConstructible*, *Cpp17CopyAssignable*, *Cpp17Swappable*, and
   *Cpp17Destructible* requirements,
 - the expressions shown in [[cpp17.nullablepointer]] are valid and have
   the indicated semantics, and
 - `P` meets all the other requirements of this subclause.
 A value-initialized object of type `P` produces the null value of the
 type. The null value shall be equivalent only to itself. A
 default-initialized object of type `P` may have an indeterminate value.
+[*Note 1*: Operations involving indeterminate values can cause
 undefined behavior. — *end note*]
 An object `p` of type `P` can be contextually converted to `bool`
 [[conv]]. The effect shall be as if `p != nullptr` had been evaluated in
 place of `p`.
 No operation which is part of the *Cpp17NullablePointer* requirements
 shall exit via an exception.
 In [[cpp17.nullablepointer]], `u` denotes an identifier, `t` denotes a
 non-`const` lvalue of type `P`, `a` and `b` denote values of type
+(possibly const) `P`, and `np` denotes a value of type (possibly const)
+`std::nullptr_t`.
 **Table: Cpp17NullablePointer requirements** <a id="cpp17.nullablepointer">[cpp17.nullablepointer]</a>
 | Expression     | Return type                                                               | Operational semantics       |
+| -------------- | ------------------------------------------------------------------------- | --------------------------- |
 | `P u(np);`<br> |                                                                           | Ensures: `u == nullptr`     |
 | `P u = np;`    |                                                                           |                             |
 | `P(np)`        |                                                                           | Ensures: `P(np) == nullptr` |
 | `t = np`       | `P&`                                                                      | Ensures: `t == nullptr`     |
+| `a != b`       | `decltype(a != b)` models `boolean-testable` | `!(a == b)`                 |
+| `a == np`      | `decltype(a == np)` and `decltype(np == a)` each model `boolean-testable` | `a == P()`                  |
 | `np == a`      |                                                                           |                             |
+| `a != np`      | `decltype(a != np)` and `decltype(np != a)` each model `boolean-testable` | `!(a == np)`                |
 | `np != a`      |                                                                           |                             |
 #### *Cpp17Hash* requirements <a id="hash.requirements">[[hash.requirements]]</a>
   and *Cpp17Destructible* ([[cpp17.destructible]]) requirements, and
 - the expressions shown in [[cpp17.hash]] are valid and have the
   indicated semantics.
 Given `Key` is an argument type for function objects of type `H`, in
+[[cpp17.hash]] `h` is a value of type (possibly const) `H`, `u` is an
 lvalue of type `Key`, and `k` is a value of a type convertible to
+(possibly const) `Key`.
 [*Note 1*: Thus all evaluations of the expression `h(k)` with the same
 value for `k` yield the same result for a given execution of the
 program. — *end note*]
 #### *Cpp17Allocator* requirements <a id="allocator.requirements">[[allocator.requirements]]</a>
+##### General <a id="allocator.requirements.general">[[allocator.requirements.general]]</a>
 The library describes a standard set of requirements for *allocators*,
 which are class-type objects that encapsulate the information about an
 allocation model. This information includes the knowledge of pointer
 types, the type of their difference, the type of the size of objects in
 this allocation model, as well as the memory allocation and deallocation
 primitives for it. All of the string types [[strings]], containers
 [[containers]] (except `array`), string buffers and string streams
 [[input.output]], and `match_results` [[re]] are parameterized in terms
 of allocators.
+In subclause [[allocator.requirements]],
+- `T`, `U`, `C` denote any cv-unqualified object type
+  [[term.object.type]],
+- `X` denotes an allocator class for type `T`,
+- `Y` denotes the corresponding allocator class for type `U`,
+- `XX` denotes the type `allocator_traits<X>`,
+- `YY` denotes the type `allocator_traits<Y>`,
+- `a`, `a1`, `a2` denote lvalues of type `X`,
+- `u` denotes the name of a variable being declared,
+- `b` denotes a value of type `Y`,
+- `c` denotes a pointer of type `C*` through which indirection is valid,
+- `p` denotes a value of type `XX::pointer` obtained by calling
+  `a1.allocate`, where `a1 == a`,
+- `q` denotes a value of type `XX::const_pointer` obtained by conversion
+  from a value `p`,
+- `r` denotes a value of type `T&` obtained by the expression `*p`,
+- `w` denotes a value of type `XX::void_pointer` obtained by conversion
+  from a value `p`,
+- `x` denotes a value of type `XX::const_void_pointer` obtained by
+  conversion from a value `q` or a value `w`,
+- `y` denotes a value of type `XX::const_void_pointer` obtained by
+  conversion from a result value of `YY::allocate`, or else a value of
+  type (possibly const) `std::nullptr_t`,
+- `n` denotes a value of type `XX::size_type`,
+- `Args` denotes a template parameter pack, and
+- `args` denotes a function parameter pack with the pattern `Args&&`.
 The class template `allocator_traits` [[allocator.traits]] supplies a
+uniform interface to all allocator types. This subclause describes the
+requirements on allocator types and thus on types used to instantiate
+`allocator_traits`. A requirement is optional if a default for a given
+type or expression is specified. Within the standard library
+`allocator_traits` template, an optional requirement that is not
+supplied by an allocator is replaced by the specified default type or
+expression.
+[*Note 1*: There are no program-defined specializations of
+`allocator_traits`. — *end note*]
+``` cpp
+typename X::pointer
+```
+*Remarks:* Default: `T*`
+``` cpp
+typename X::const_pointer
+```
+*Mandates:* `XX::pointer` is convertible to `XX::const_pointer`.
+*Remarks:* Default: `pointer_traits<XX::pointer>::rebind<const T>`
+``` cpp
+typename X::void_pointer
+typename Y::void_pointer
+```
+*Mandates:* `XX::pointer` is convertible to `XX::void_pointer`.
+`XX::void_pointer` and `YY::void_pointer` are the same type.
+*Remarks:* Default: `pointer_traits<XX::pointer>::rebind<void>`
+``` cpp
+typename X::const_void_pointer
+typename Y::const_void_pointer
+```
+*Mandates:* `XX::pointer`, `XX::const_pointer`, and `XX::void_pointer`
+are convertible to `XX::const_void_pointer`. `XX::const_void_pointer`
+and `YY::const_void_pointer` are the same type.
+*Remarks:* Default: `pointer_traits<XX::pointer>::rebind<const void>`
+``` cpp
+typename X::value_type
+```
+*Result:* Identical to `T`.
+``` cpp
+typename X::size_type
+```
+*Result:* An unsigned integer type that can represent the size of the
+largest object in the allocation model.
+*Remarks:* Default: `make_unsigned_t<XX::difference_type>`
+``` cpp
+typename X::difference_type
+```
+*Result:* A signed integer type that can represent the difference
+between any two pointers in the allocation model.
+*Remarks:* Default: `pointer_traits<XX::pointer>::difference_type`
+``` cpp
+typename X::template rebind<U>::other
+```
+*Result:* `Y`
+*Ensures:* For all `U` (including `T`), `YY::rebind_alloc<T>` is `X`.
+*Remarks:* If `Allocator` is a class template instantiation of the form
 `SomeAllocator<T, Args>`, where `Args` is zero or more type arguments,
 and `Allocator` does not supply a `rebind` member template, the standard
 `allocator_traits` template uses `SomeAllocator<U, Args>` in place of
+`Allocator::rebind<U>::other` by default. For allocator types that are
 not template instantiations of the above form, no default is provided.
+[*Note 1*: The member class template `rebind` of `X` is effectively a
+typedef template. In general, if the name `Allocator` is bound to
+`SomeAllocator<T>`, then `Allocator::rebind<U>::other` is the same type
+as `SomeAllocator<U>`, where `SomeAllocator<T>::value_type` is `T` and
+`SomeAllocator<U>::value_type` is `U`. — *end note*]
+``` cpp
+*p
+```
+*Result:* `T&`
+``` cpp
+*q
+```
+*Result:* `const T&`
+*Ensures:* `*q` refers to the same object as `*p`.
+``` cpp
+p->m
+```
+*Result:* Type of `T::m`.
+*Preconditions:* `(*p).m` is well-defined.
+*Effects:* Equivalent to `(*p).m`.
+``` cpp
+q->m
+```
+*Result:* Type of `T::m`.
+*Preconditions:* `(*q).m` is well-defined.
+*Effects:* Equivalent to `(*q).m`.
+``` cpp
+static_cast<XX::pointer>(w)
+```
+*Result:* `XX::pointer`
+*Ensures:* `static_cast<XX::pointer>(w) == p`.
+``` cpp
+static_cast<XX::const_pointer>(x)
+```
+*Result:* `XX::const_pointer`
+*Ensures:* `static_cast<XX::const_pointer>(x) == q`.
+``` cpp
+pointer_traits<XX::pointer>::pointer_to(r)
+```
+*Result:* `XX::pointer`
+*Ensures:* Same as `p`.
+``` cpp
+a.allocate(n)
+```
+*Result:* `XX::pointer`
+*Effects:* Memory is allocated for an array of `n` `T` and such an
+object is created but array elements are not constructed.
+[*Example 1*: When reusing storage denoted by some pointer value `p`,
+`launder(reinterpret_cast<T*>(new (p) byte[n * sizeof(T)]))` can be used
+to implicitly create a suitable array object and obtain a pointer to
+it. — *end example*]
+*Throws:* `allocate` may throw an appropriate exception.
+[*Note 2*: It is intended that `a.allocate` be an efficient means of
+allocating a single object of type `T`, even when `sizeof(T)` is small.
+That is, there is no need for a container to maintain its own free
+list. — *end note*]
+*Remarks:* If `n == 0`, the return value is unspecified.
+``` cpp
+a.allocate(n, y)
+```
+*Result:* `XX::pointer`
+*Effects:* Same as `a.allocate(n)`. The use of `y` is unspecified, but
+it is intended as an aid to locality.
+*Remarks:* Default: `a.allocate(n)`
+``` cpp
+a.allocate_at_least(n)
+```
+*Result:* `allocation_result<XX::pointer, XX::size_type>`
+*Returns:* `allocation_result<XX::pointer, XX::size_type>{ptr, count}`
+where `ptr` is memory allocated for an array of `count` `T` and such an
+object is created but array elements are not constructed, such that
+`count` ≥ `n`. If `n == 0`, the return value is unspecified.
+*Throws:* `allocate_at_least` may throw an appropriate exception.
+*Remarks:* Default: `{a.allocate(n), n}`.
+``` cpp
+a.deallocate(p, n)
+```
+*Result:* (not used)
+*Preconditions:*
+- If `p` is memory that was obtained by a call to `a.allocate_at_least`,
+  let `ret` be the value returned and `req` be the value passed as the
+  first argument of that call. `p` is equal to `ret.ptr` and `n` is a
+  value such that `req` ≤ `n` ≤ `ret.count`.
+- Otherwise, `p` is a pointer value obtained from `allocate`. `n` equals
+  the value passed as the first argument to the invocation of `allocate`
+  which returned `p`.
+`p` has not been invalidated by an intervening call to `deallocate`.
+*Throws:* Nothing.
+``` cpp
+a.max_size()
+```
+*Result:* `XX::size_type`
+*Returns:* The largest value `n` that can meaningfully be passed to
+`a.allocate(n)`.
+*Remarks:* Default:
+`numeric_limits<size_type>::max() / sizeof(value_type)`
+``` cpp
+a1 == a2
+```
+*Result:* `bool`
+*Returns:* `true` only if storage allocated from each can be deallocated
+via the other.
+*Throws:* Nothing.
+*Remarks:* `operator==` shall be reflexive, symmetric, and transitive.
+``` cpp
+a1 != a2
+```
+*Result:* `bool`
+*Returns:* `!(a1 == a2)`.
+``` cpp
+a == b
+```
+*Result:* `bool`
+*Returns:* `a == YY::rebind_alloc<T>(b)`.
+``` cpp
+a != b
+```
+*Result:* `bool`
+*Returns:* `!(a == b)`.
+``` cpp
+X u(a);
+X u = a;
+```
+*Ensures:* `u == a`
+*Throws:* Nothing.
+``` cpp
+X u(b);
+```
+*Ensures:* `Y(u) == b` and `u == X(b)`.
+*Throws:* Nothing.
+``` cpp
+X u(std::move(a));
+X u = std::move(a);
+```
+*Ensures:* The value of `a` is unchanged and is equal to `u`.
+*Throws:* Nothing.
+``` cpp
+X u(std::move(b));
+```
+*Ensures:* `u` is equal to the prior value of `X(b)`.
+*Throws:* Nothing.
+``` cpp
+a.construct(c, args)
+```
+*Result:* (not used)
+*Effects:* Constructs an object of type `C` at `c`.
+*Remarks:* Default: `construct_at(c, std::forward<Args>(args)...)`
+``` cpp
+a.destroy(c)
+```
+*Result:* (not used)
+*Effects:* Destroys the object at `c`.
+*Remarks:* Default: `destroy_at(c)`
+``` cpp
+a.select_on_container_copy_construction()
+```
+*Result:* `X`
+*Returns:* Typically returns either `a` or `X()`.
+*Remarks:* Default: `return a;`
+``` cpp
+typename X::propagate_on_container_copy_assignment
+```
+*Result:* Identical to or derived from `true_type` or `false_type`.
+*Returns:* `true_type` only if an allocator of type `X` should be copied
+when the client container is copy-assigned; if so, `X` shall meet the
+*Cpp17CopyAssignable* requirements ([[cpp17.copyassignable]]) and the
+copy operation shall not throw exceptions.
+*Remarks:* Default: `false_type`
+``` cpp
+typename X::propagate_on_container_move_assignment
+```
+*Result:* Identical to or derived from `true_type` or `false_type`.
+*Returns:* `true_type` only if an allocator of type `X` should be moved
+when the client container is move-assigned; if so, `X` shall meet the
+*Cpp17MoveAssignable* requirements ([[cpp17.moveassignable]]) and the
+move operation shall not throw exceptions.
+*Remarks:* Default: `false_type`
+``` cpp
+typename X::propagate_on_container_swap
+```
+*Result:* Identical to or derived from `true_type` or `false_type`.
+*Returns:* `true_type` only if an allocator of type `X` should be
+swapped when the client container is swapped; if so, `X` shall meet the
+*Cpp17Swappable* requirements [[swappable.requirements]] and the `swap`
+operation shall not throw exceptions.
+*Remarks:* Default: `false_type`
+``` cpp
+typename X::is_always_equal
+```
+*Result:* Identical to or derived from `true_type` or `false_type`.
+*Returns:* `true_type` only if the expression `a1 == a2` is guaranteed
+to be `true` for any two (possibly const) values `a1`, `a2` of type `X`.
+*Remarks:* Default: `is_empty<X>::type`
 An allocator type `X` shall meet the *Cpp17CopyConstructible*
+requirements ([[cpp17.copyconstructible]]). The `XX::pointer`,
+`XX::const_pointer`, `XX::void_pointer`, and `XX::const_void_pointer`
+types shall meet the *Cpp17NullablePointer* requirements (
+[[cpp17.nullablepointer]]). No constructor, comparison operator
+function, copy operation, move operation, or swap operation on these
+pointer types shall exit via an exception. `XX::pointer` and
+`XX::const_pointer` shall also meet the requirements for a
+*Cpp17RandomAccessIterator* [[random.access.iterators]] and the
+additional requirement that, when `p` and `(p + n)` are dereferenceable
+pointer values for some integral value `n`,
 ``` cpp
+addressof(*(p + n)) == addressof(*p) + n
 ```
 is `true`.
 Let `x1` and `x2` denote objects of (possibly different) types
+`XX::void_pointer`, `XX::const_void_pointer`, `XX::pointer`, or
+`XX::const_pointer`. Then, `x1` and `x2` are *equivalently-valued*
 pointer values, if and only if both `x1` and `x2` can be explicitly
 converted to the two corresponding objects `px1` and `px2` of type
+`XX::const_pointer`, using a sequence of `static_cast`s using only these
 four types, and the expression `px1 == px2` evaluates to `true`.
+Let `w1` and `w2` denote objects of type `XX::void_pointer`. Then for
+the expressions
 ``` cpp
 w1 == w2
 w1 != w2
 ```
 either or both objects may be replaced by an equivalently-valued object
+of type `XX::const_void_pointer` with no change in semantics.
+Let `p1` and `p2` denote objects of type `XX::pointer`. Then for the
 expressions
 ``` cpp
 p1 == p2
 p1 != p2
 p1 > p2
 p1 - p2
 ```
 either or both objects may be replaced by an equivalently-valued object
+of type `XX::const_pointer` with no change in semantics.
 An allocator may constrain the types on which it can be instantiated and
 the arguments for which its `construct` or `destroy` members may be
 called. If a type cannot be used with a particular allocator, the
 allocator class or the call to `construct` or `destroy` may fail to
 If the alignment associated with a specific over-aligned type is not
 supported by an allocator, instantiation of the allocator for that type
 may fail. The allocator also may silently ignore the requested
 alignment.
+[*Note 2*: Additionally, the member function `allocate` for that type
+can fail by throwing an object of type `bad_alloc`. — *end note*]
 [*Example 1*:
 The following is an allocator class template supporting the minimal
+interface that meets the requirements of
+[[allocator.requirements.general]]:
 ``` cpp
+template<class T>
 struct SimpleAllocator {
+ using value_type = T;
   SimpleAllocator(ctor args);
+  template<class U> SimpleAllocator(const SimpleAllocator<U>& other);
+ T* allocate(std::size_t n);
+  void deallocate(T* p, std::size_t n);
+  template<class U> bool operator==(const SimpleAllocator<U>& rhs) const;
 };
 ```
 — *end example*]
 ##### Allocator completeness requirements <a id="allocator.requirements.completeness">[[allocator.requirements.completeness]]</a>

Diff to HTML by rtfpessoa