[mem.poly.allocator.class] - C++17 → C++20

Files changed (1) hide show

tmp/tmplznnwyvm/{from.md → to.md} +112 -149

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

@@ -1,19 +1,23 @@
 ### Class template `polymorphic_allocator` <a id="mem.poly.allocator.class">[[mem.poly.allocator.class]]</a>
-A specialization of class template `pmr::polymorphic_allocator` conforms
-to the `Allocator` requirements ([[allocator.requirements]]).
-Constructed with different memory resources, different instances of the
-same specialization of `pmr::polymorphic_allocator` can exhibit entirely
 different allocation behavior. This runtime polymorphism allows objects
 that use `polymorphic_allocator` to behave as if they used different
 allocator types at run time even though they use the same static
 allocator type.
 ``` cpp
-template <class Tp>
-class polymorphic_allocator {
     memory_resource* memory_rsrc;       // exposition only
   public:
     using value_type = Tp;
@@ -24,42 +28,37 @@ public:
     polymorphic_allocator(const polymorphic_allocator& other) = default;
     template<class U>
       polymorphic_allocator(const polymorphic_allocator<U>& other) noexcept;
- polymorphic_allocator&
-    operator=(const polymorphic_allocator& rhs) = delete;
     // [mem.poly.allocator.mem], member functions
- Tp* allocate(size_t n);
     void deallocate(Tp* p, size_t n);
     template<class T, class... Args>
       void construct(T* p, Args&&... args);
-  template <class T1, class T2, class... Args1, class... Args2>
-    void construct(pair<T1,T2>* p, piecewise_construct_t,
-                   tuple<Args1...> x, tuple<Args2...> y);
-  template <class T1, class T2>
-    void construct(pair<T1,T2>* p);
-  template <class T1, class T2, class U, class V>
-    void construct(pair<T1,T2>* p, U&& x, V&& y);
-  template <class T1, class T2, class U, class V>
-    void construct(pair<T1,T2>* p, const pair<U, V>& pr);
-  template <class T1, class T2, class U, class V>
-    void construct(pair<T1,T2>* p, pair<U, V>&& pr);
     template<class T>
       void destroy(T* p);
     polymorphic_allocator select_on_container_copy_construction() const;
     memory_resource* resource() const;
   };
 ```
-#### `polymorphic_allocator` constructors <a id="mem.poly.allocator.ctor">[[mem.poly.allocator.ctor]]</a>
 ``` cpp
 polymorphic_allocator() noexcept;
 ```
@@ -67,171 +66,143 @@ polymorphic_allocator() noexcept;
 ``` cpp
 polymorphic_allocator(memory_resource* r);
 ```
-*Requires:* `r` is non-null.
 *Effects:* Sets `memory_rsrc` to `r`.
 *Throws:* Nothing.
 [*Note 1*: This constructor provides an implicit conversion from
 `memory_resource*`. — *end note*]
 ``` cpp
-template <class U>
-  polymorphic_allocator(const polymorphic_allocator<U>& other) noexcept;
 ```
 *Effects:* Sets `memory_rsrc` to `other.resource()`.
-#### `polymorphic_allocator` member functions <a id="mem.poly.allocator.mem">[[mem.poly.allocator.mem]]</a>
 ``` cpp
-Tp* allocate(size_t n);
 ```
-*Returns:* Equivalent to
 ``` cpp
 return static_cast<Tp*>(memory_rsrc->allocate(n * sizeof(Tp), alignof(Tp)));
 ```
 ``` cpp
 void deallocate(Tp* p, size_t n);
 ```
-*Requires:* `p` was allocated from a memory resource `x`, equal to
 `*memory_rsrc`, using `x.allocate(n * sizeof(Tp), alignof(Tp))`.
 *Effects:* Equivalent to
 `memory_rsrc->deallocate(p, n * sizeof(Tp), alignof(Tp))`.
 *Throws:* Nothing.
 ``` cpp
 template<class T, class... Args>
   void construct(T* p, Args&&... args);
 ```
-*Requires:* Uses-allocator construction of `T` with allocator
-`resource()` (see  [[allocator.uses.construction]]) and constructor
-arguments `std::forward<Args>(args)...` is well-formed.
-[*Note 1*: Uses-allocator construction is always well formed for types
-that do not use allocators. — *end note*]
 *Effects:* Construct a `T` object in the storage whose address is
-represented by `p` by uses-allocator construction with allocator
-`resource()` and constructor arguments `std::forward<Args>(args)...`.
 *Throws:* Nothing unless the constructor for `T` throws.
-``` cpp
-template <class T1, class T2, class... Args1, class... Args2>
-  void construct(pair<T1,T2>* p, piecewise_construct_t,
-                 tuple<Args1...> x, tuple<Args2...> y);
-```
-[*Note 2*: This method and the `construct` methods that follow are
-overloads for piecewise construction of
-pairs ([[pairs.pair]]). — *end note*]
-*Effects:* Let `xprime` be a `tuple` constructed from `x` according to
-the appropriate rule from the following list.
-[*Note 3*: The following description can be summarized as constructing
-a `pair<T1, T2>` object in the storage whose address is represented by
-`p`, as if by separate uses-allocator construction with allocator
-`resource()` ([[allocator.uses.construction]]) of `p->first` using the
-elements of `x` and `p->second` using the elements of
-`y`. — *end note*]
-- If `uses_allocator_v<T1,memory_resource*>` is `false`
-  and `is_constructible_v<T1,Args1...>` is `true`,
-  then `xprime` is `x`.
-- Otherwise, if `uses_allocator_v<T1,memory_resource*>` is `true`
-  and `is_constructible_v<T1,allocator_arg_t,memory_resource*,Args1...>`
-  is `true`,
-  then `xprime` is
-  `tuple_cat(make_tuple(allocator_arg, resource()), std::move(x))`.
-- Otherwise, if `uses_allocator_v<T1,memory_resource*>` is `true`
-  and `is_constructible_v<T1,Args1...,memory_resource*>` is `true`,
-  then `xprime` is `tuple_cat(std::move(x), make_tuple(resource()))`.
-- Otherwise the program is ill formed.
-Let `yprime` be a tuple constructed from `y` according to the
-appropriate rule from the following list:
-- If `uses_allocator_v<T2,memory_resource*>` is `false`
-  and `is_constructible_v<T2,Args2...>` is `true`,
-  then `yprime` is `y`.
-- Otherwise, if `uses_allocator_v<T2,memory_resource*>` is `true`
-  and `is_constructible_v<T2,allocator_arg_t,memory_resource*,Args2...>`
-  is `true`,
-  then `yprime` is
-  `tuple_cat(make_tuple(allocator_arg, resource()), std::move(y))`.
-- Otherwise, if `uses_allocator_v<T2,memory_resource*>` is `true`
-  and `is_constructible_v<T2,Args2...,memory_resource*>` is `true`,
-  then `yprime` is `tuple_cat(std::move(y), make_tuple(resource()))`.
-- Otherwise the program is ill formed.
-Then, using `piecewise_construct`, `xprime`, and `yprime` as the
-constructor arguments, this function constructs a `pair<T1, T2>` object
-in the storage whose address is represented by `p`.
-``` cpp
-template <class T1, class T2>
-  void construct(pair<T1,T2>* p);
-```
-*Effects:* Equivalent to:
-``` cpp
-construct(p, piecewise_construct, tuple<>(), tuple<>());
-```
-``` cpp
-template <class T1, class T2, class U, class V>
-  void construct(pair<T1,T2>* p, U&& x, V&& y);
-```
-*Effects:* Equivalent to:
-``` cpp
-construct(p, piecewise_construct,
-          forward_as_tuple(std::forward<U>(x)),
-          forward_as_tuple(std::forward<V>(y)));
-```
-``` cpp
-template <class T1, class T2, class U, class V>
-  void construct(pair<T1,T2>* p, const pair<U, V>& pr);
-```
-*Effects:* Equivalent to:
-``` cpp
-construct(p, piecewise_construct,
-          forward_as_tuple(pr.first),
-          forward_as_tuple(pr.second));
-```
-``` cpp
-template <class T1, class T2, class U, class V>
-  void construct(pair<T1,T2>* p, pair<U, V>&& pr);
-```
-*Effects:* Equivalent to:
-``` cpp
-construct(p, piecewise_construct,
-          forward_as_tuple(std::forward<U>(pr.first)),
-          forward_as_tuple(std::forward<V>(pr.second)));
-```
 ``` cpp
 template<class T>
   void destroy(T* p);
 ```
@@ -249,23 +220,15 @@ polymorphic_allocator select_on_container_copy_construction() const;
 memory_resource* resource() const;
 ```
 *Returns:* `memory_rsrc`.
-#### `polymorphic_allocator` equality <a id="mem.poly.allocator.eq">[[mem.poly.allocator.eq]]</a>
 ``` cpp
 template<class T1, class T2>
   bool operator==(const polymorphic_allocator<T1>& a,
                   const polymorphic_allocator<T2>& b) noexcept;
 ```
 *Returns:* `*a.resource() == *b.resource()`.
-``` cpp
-template <class T1, class T2>
-  bool operator!=(const polymorphic_allocator<T1>& a,
-                  const polymorphic_allocator<T2>& b) noexcept;
-```
-*Returns:* `!(a == b)`.

 ### Class template `polymorphic_allocator` <a id="mem.poly.allocator.class">[[mem.poly.allocator.class]]</a>
+A specialization of class template `pmr::polymorphic_allocator` meets
+the *Cpp17Allocator* requirements ([[cpp17.allocator]]). Constructed
+with different memory resources, different instances of the same
+specialization of `pmr::polymorphic_allocator` can exhibit entirely
 different allocation behavior. This runtime polymorphism allows objects
 that use `polymorphic_allocator` to behave as if they used different
 allocator types at run time even though they use the same static
 allocator type.
+All specializations of class template `pmr::polymorphic_allocator` meet
+the allocator completeness requirements
+[[allocator.requirements.completeness]].
 ``` cpp
+namespace std::pmr {
+  template<class Tp = byte> class polymorphic_allocator {
     memory_resource* memory_rsrc;       // exposition only
   public:
     using value_type = Tp;
     polymorphic_allocator(const polymorphic_allocator& other) = default;
     template<class U>
       polymorphic_allocator(const polymorphic_allocator<U>& other) noexcept;
+ polymorphic_allocator& operator=(const polymorphic_allocator&) = delete;
     // [mem.poly.allocator.mem], member functions
+    [[nodiscard]] Tp* allocate(size_t n);
     void deallocate(Tp* p, size_t n);
+    [[nodiscard]] void* allocate_bytes(size_t nbytes, size_t alignment = alignof(max_align_t));
+    void deallocate_bytes(void* p, size_t nbytes, size_t alignment = alignof(max_align_t));
+    template<class T> [[nodiscard]] T* allocate_object(size_t n = 1);
+    template<class T> void deallocate_object(T* p, size_t n = 1);
+    template<class T, class... CtorArgs> [[nodiscard]] T* new_object(CtorArgs&&... ctor_args);
+    template<class T> void delete_object(T* p);
     template<class T, class... Args>
       void construct(T* p, Args&&... args);
     template<class T>
       void destroy(T* p);
     polymorphic_allocator select_on_container_copy_construction() const;
     memory_resource* resource() const;
   };
+}
 ```
+#### Constructors <a id="mem.poly.allocator.ctor">[[mem.poly.allocator.ctor]]</a>
 ``` cpp
 polymorphic_allocator() noexcept;
 ```
 ``` cpp
 polymorphic_allocator(memory_resource* r);
 ```
+*Preconditions:* `r` is non-null.
 *Effects:* Sets `memory_rsrc` to `r`.
 *Throws:* Nothing.
 [*Note 1*: This constructor provides an implicit conversion from
 `memory_resource*`. — *end note*]
 ``` cpp
+template<class U> polymorphic_allocator(const polymorphic_allocator<U>& other) noexcept;
 ```
 *Effects:* Sets `memory_rsrc` to `other.resource()`.
+#### Member functions <a id="mem.poly.allocator.mem">[[mem.poly.allocator.mem]]</a>
 ``` cpp
+[[nodiscard]] Tp* allocate(size_t n);
 ```
+*Effects:* If `numeric_limits<size_t>::max() / sizeof(Tp) < n`, throws
+`bad_array_new_length`. Otherwise equivalent to:
 ``` cpp
 return static_cast<Tp*>(memory_rsrc->allocate(n * sizeof(Tp), alignof(Tp)));
 ```
 ``` cpp
 void deallocate(Tp* p, size_t n);
 ```
+*Preconditions:* `p` was allocated from a memory resource `x`, equal to
 `*memory_rsrc`, using `x.allocate(n * sizeof(Tp), alignof(Tp))`.
 *Effects:* Equivalent to
 `memory_rsrc->deallocate(p, n * sizeof(Tp), alignof(Tp))`.
 *Throws:* Nothing.
+``` cpp
+[[nodiscard]] void* allocate_bytes(size_t nbytes, size_t alignment = alignof(max_align_t));
+```
+*Effects:* Equivalent to:
+`return memory_rsrc->allocate(nbytes, alignment);`
+[*Note 1*: The return type is `void*` (rather than, e.g., `byte*`) to
+support conversion to an arbitrary pointer type `U*` by
+`static_cast<U*>`, thus facilitating construction of a `U` object in the
+allocated memory. — *end note*]
+``` cpp
+void deallocate_bytes(void* p, size_t nbytes, size_t alignment = alignof(max_align_t));
+```
+*Effects:* Equivalent to
+`memory_rsrc->deallocate(p, nbytes, alignment)`.
+``` cpp
+template<class T>
+  [[nodiscard]] T* allocate_object(size_t n = 1);
+```
+*Effects:* Allocates memory suitable for holding an array of `n` objects
+of type `T`, as follows:
+- if `numeric_limits<size_t>::max() / sizeof(T) < n`, throws
+  `bad_array_new_length`,
+- otherwise equivalent to:
+  ``` cpp
+  return static_cast<T*>(allocate_bytes(n*sizeof(T), alignof(T)));
+  ```
+[*Note 2*: `T` is not deduced and must therefore be provided as a
+template argument. — *end note*]
+``` cpp
+template<class T>
+  void deallocate_object(T* p, size_t n = 1);
+```
+*Effects:* Equivalent to `deallocate_bytes(p, n*sizeof(T), alignof(T))`.
+``` cpp
+template<class T, class CtorArgs...>
+  [[nodiscard]] T* new_object(CtorArgs&&... ctor_args);
+```
+*Effects:* Allocates and constructs an object of type `T`, as follows.
+Equivalent to:
+``` cpp
+T* p = allocate_object<T>();
+try {
+  construct(p, std::forward<CtorArgs>(ctor_args)...);
+} catch (...) {
+  deallocate_object(p);
+  throw;
+}
+return p;
+```
+[*Note 3*: `T` is not deduced and must therefore be provided as a
+template argument. — *end note*]
+``` cpp
+template<class T>
+  void delete_object(T* p);
+```
+*Effects:* Equivalent to:
+``` cpp
+destroy(p);
+deallocate_object(p);
+```
 ``` cpp
 template<class T, class... Args>
   void construct(T* p, Args&&... args);
 ```
+*Mandates:* Uses-allocator construction of `T` with allocator `*this`
+(see  [[allocator.uses.construction]]) and constructor arguments
+`std::forward<Args>(args)...` is well-formed.
 *Effects:* Construct a `T` object in the storage whose address is
+represented by `p` by uses-allocator construction with allocator `*this`
+and constructor arguments `std::forward<Args>(args)...`.
 *Throws:* Nothing unless the constructor for `T` throws.
 ``` cpp
 template<class T>
   void destroy(T* p);
 ```
 memory_resource* resource() const;
 ```
 *Returns:* `memory_rsrc`.
+#### Equality <a id="mem.poly.allocator.eq">[[mem.poly.allocator.eq]]</a>
 ``` cpp
 template<class T1, class T2>
   bool operator==(const polymorphic_allocator<T1>& a,
                   const polymorphic_allocator<T2>& b) noexcept;
 ```
 *Returns:* `*a.resource() == *b.resource()`.

Diff to HTML by rtfpessoa