[allocator.requirements] - C++17 → C++20

Files changed (1) hide show

tmp/tmp54msvx41/{from.md → to.md} +52 -47

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

@@ -1,32 +1,31 @@
-#### Allocator 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 (Clause  [[strings]]),
-containers (Clause  [[containers]]) (except array), string buffers and
-string streams (Clause  [[input.output]]), and `match_results` (Clause
-[[re]]) are parameterized in terms of allocators.
-The class template `allocator_traits` ([[allocator.traits]]) supplies a
-uniform interface to all allocator types. Table  [[tab:desc.var.def]]
-describes the types manipulated through allocators. Table
-[[tab:utilities.allocator.requirements]] describes the requirements on
-allocator types and thus on types used to instantiate
-`allocator_traits`. A requirement is optional if the last column of
-Table  [[tab:utilities.allocator.requirements]] 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:desc.var.def]] and
-[[tab:utilities.allocator.requirements]], 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.
@@ -42,29 +41,36 @@ 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 satisfy the `CopyAssignable` requirements (Table
-[[tab:copyassignable]]) and the copy operation shall not throw
 exceptions. If `X::propagate_on_container_move_assignment::value` is
-`true`, `X` shall satisfy the `MoveAssignable` requirements (Table
-[[tab: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 satisfy the requirements of
-`CopyConstructible` ([[utility.arg.requirements]]). The `X::pointer`,
 `X::const_pointer`, `X::void_pointer`, and `X::const_void_pointer` types
-shall satisfy the requirements of `NullablePointer` (
-[[nullablepointer.requirements]]). 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 satisfy the requirements for a random access iterator (
-[[random.access.iterators]]) and of a contiguous iterator (
-[[iterator.requirements.general]]).
 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
@@ -103,25 +109,32 @@ 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
 instantiate.
 [*Example 1*:
 The following is an allocator class template supporting the minimal
-interface that satisfies the requirements of Table
-[[tab:utilities.allocator.requirements]]:
 ``` cpp
 template<class Tp>
 struct SimpleAllocator {
   typedef Tp value_type;
   SimpleAllocator(ctor args);
   template<class T> SimpleAllocator(const SimpleAllocator<T>& other);
-  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>&);
@@ -129,23 +142,15 @@ template <class T, class U>
 bool operator!=(const SimpleAllocator<T>&, const SimpleAllocator<U>&);
 ```
 — *end example*]
-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*]
 ##### Allocator completeness requirements <a id="allocator.requirements.completeness">[[allocator.requirements.completeness]]</a>
-If `X` is an allocator class for type `T`, `X` additionally satisfies
-the allocator completeness requirements if, whether or not `T` is a
-complete type:
 - `X` is a complete type, and
-- all the member types of `allocator_traits<X>` ([[allocator.traits]])
   other than `value_type` are complete types.

+#### *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.
 `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
 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
 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>&);
 bool operator!=(const SimpleAllocator<T>&, const SimpleAllocator<U>&);
 ```
 — *end example*]
 ##### Allocator completeness requirements <a id="allocator.requirements.completeness">[[allocator.requirements.completeness]]</a>
+If `X` is an allocator class for type `T`, `X` additionally meets the
+allocator completeness requirements if, whether or not `T` is a complete
+type:
 - `X` is a complete type, and
+- all the member types of `allocator_traits<X>` [[allocator.traits]]
   other than `value_type` are complete types.

Diff to HTML by rtfpessoa