[inplace.vector] - C++23 → Trunk

Files changed (1) hide show

tmp/tmpear43rv3/{from.md → to.md} +453 -0

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

	@@ -0,0 +1,453 @@

+### Class template `inplace_vector` <a id="inplace.vector">[[inplace.vector]]</a>
+#### Overview <a id="inplace.vector.overview">[[inplace.vector.overview]]</a>
+An `inplace_vector` is a contiguous container. Its capacity is fixed and
+its elements are stored within the `inplace_vector` object itself.
+An `inplace_vector` meets all of the requirements of a container
+[[container.reqmts]], of a reversible container
+[[container.rev.reqmts]], of a contiguous container, and of a sequence
+container, including most of the optional sequence container
+requirements [[sequence.reqmts]]. The exceptions are the `push_front`,
+`prepend_range`, `pop_front`, and `emplace_front` member functions,
+which are not provided. Descriptions are provided here only for
+operations on `inplace_vector` that are not described in one of these
+tables or for operations where there is additional semantic information.
+For any `N`, `inplace_vector<T, N>::iterator` and
+`inplace_vector<T, N>::const_iterator` meet the constexpr iterator
+requirements.
+Any member function of `inplace_vector<T, N>` that would cause the size
+to exceed `N` throws an exception of type `bad_alloc`.
+Let `IV` denote a specialization of `inplace_vector<T, N>`. If `N` is
+zero, then `IV` is trivially copyable and empty, and
+`std::is_trivially_default_constructible_v<IV>` is `true`. Otherwise:
+- If `is_trivially_copy_constructible_v<T>` is `true`, then `IV` has a
+  trivial copy constructor.
+- If `is_trivially_move_constructible_v<T>` is `true`, then `IV` has a
+  trivial move constructor.
+- If `is_trivially_destructible_v<T>` is `true`, then:
+  - `IV` has a trivial destructor.
+  - If
+    ``` cpp
+    is_trivially_copy_constructible_v<T> && is_trivially_copy_assignable_v<T>
+    ```
+    is `true`, then `IV` has a trivial copy assignment operator.
+  - If
+    ``` cpp
+    is_trivially_move_constructible_v<T> && is_trivially_move_assignable_v<T>
+    ```
+    is `true`, then `IV` has a trivial move assignment operator.
+``` cpp
+namespace std {
+  template<class T, size_t N>
+  class inplace_vector {
+  public:
+    // types:
+    using value_type             = T;
+    using pointer                = T*;
+    using const_pointer          = const T*;
+    using reference              = value_type&;
+    using const_reference        = const value_type&;
+    using size_type              = size_t;
+    using difference_type        = ptrdiff_t;
+    using iterator               = implementation-defined  // type of inplace_vector::iterator; // see [container.requirements]
+    using const_iterator         = implementation-defined  // type of inplace_vector::const_iterator; // see [container.requirements]
+    using reverse_iterator       = std::reverse_iterator<iterator>;
+    using const_reverse_iterator = std::reverse_iterator<const_iterator>;
+    // [inplace.vector.cons], construct/copy/destroy
+    constexpr inplace_vector() noexcept;
+    constexpr explicit inplace_vector(size_type n);                         // freestanding-deleted
+    constexpr inplace_vector(size_type n, const T& value);                  // freestanding-deleted
+    template<class InputIterator>
+      constexpr inplace_vector(InputIterator first, InputIterator last);    // freestanding-deleted
+    template<container-compatible-range<T> R>
+      constexpr inplace_vector(from_range_t, R&& rg);                       // freestanding-deleted
+    constexpr inplace_vector(const inplace_vector&);
+    constexpr inplace_vector(inplace_vector&&)
+      noexcept(N == 0 || is_nothrow_move_constructible_v<T>);
+    constexpr inplace_vector(initializer_list<T> il);                       // freestanding-deleted
+    constexpr ~inplace_vector();
+    constexpr inplace_vector& operator=(const inplace_vector& other);
+    constexpr inplace_vector& operator=(inplace_vector&& other)
+      noexcept(N == 0 || (is_nothrow_move_assignable_v<T> &&
+                          is_nothrow_move_constructible_v<T>));
+    constexpr inplace_vector& operator=(initializer_list<T>);               // freestanding-deleted
+    template<class InputIterator>
+      constexpr void assign(InputIterator first, InputIterator last);       // freestanding-deleted
+    template<container-compatible-range<T> R>
+      constexpr void assign_range(R&& rg);                                  // freestanding-deleted
+    constexpr void assign(size_type n, const T& u);                         // freestanding-deleted
+    constexpr void assign(initializer_list<T> il);                          // freestanding-deleted
+    // iterators
+    constexpr iterator               begin()         noexcept;
+    constexpr const_iterator         begin()   const noexcept;
+    constexpr iterator               end()           noexcept;
+    constexpr const_iterator         end()     const noexcept;
+    constexpr reverse_iterator       rbegin()        noexcept;
+    constexpr const_reverse_iterator rbegin()  const noexcept;
+    constexpr reverse_iterator       rend()          noexcept;
+    constexpr const_reverse_iterator rend()    const noexcept;
+    constexpr const_iterator         cbegin()  const noexcept;
+    constexpr const_iterator         cend()    const noexcept;
+    constexpr const_reverse_iterator crbegin() const noexcept;
+    constexpr const_reverse_iterator crend()   const noexcept;
+    // [inplace.vector.capacity], capacity
+    constexpr bool empty() const noexcept;
+    constexpr size_type size() const noexcept;
+    static constexpr size_type max_size() noexcept;
+    static constexpr size_type capacity() noexcept;
+    constexpr void resize(size_type sz);                                    // freestanding-deleted
+    constexpr void resize(size_type sz, const T& c);                        // freestanding-deleted
+    static constexpr void reserve(size_type n);                             // freestanding-deleted
+    static constexpr void shrink_to_fit() noexcept;
+    // element access
+    constexpr reference       operator[](size_type n);
+    constexpr const_reference operator[](size_type n) const;
+    constexpr reference       at(size_type n);                              // freestanding-deleted
+    constexpr const_reference at(size_type n) const;                        // freestanding-deleted
+    constexpr reference       front();
+    constexpr const_reference front() const;
+    constexpr reference       back();
+    constexpr const_reference back() const;
+    // [inplace.vector.data], data access
+    constexpr       T* data()       noexcept;
+    constexpr const T* data() const noexcept;
+    // [inplace.vector.modifiers], modifiers
+    template<class... Args>
+      constexpr reference emplace_back(Args&&... args);                     // freestanding-deleted
+    constexpr reference push_back(const T& x);                              // freestanding-deleted
+    constexpr reference push_back(T&& x);                                   // freestanding-deleted
+    template<container-compatible-range<T> R>
+      constexpr void append_range(R&& rg);                                  // freestanding-deleted
+    constexpr void pop_back();
+    template<class... Args>
+      constexpr pointer try_emplace_back(Args&&... args);
+    constexpr pointer try_push_back(const T& x);
+    constexpr pointer try_push_back(T&& x);
+    template<container-compatible-range<T> R>
+      constexpr ranges::borrowed_iterator_t<R> try_append_range(R&& rg);
+    template<class... Args>
+      constexpr reference unchecked_emplace_back(Args&&... args);
+    constexpr reference unchecked_push_back(const T& x);
+    constexpr reference unchecked_push_back(T&& x);
+    template<class... Args>
+      constexpr iterator emplace(const_iterator position, Args&&... args);  // freestanding-deleted
+    constexpr iterator insert(const_iterator position, const T& x);         // freestanding-deleted
+    constexpr iterator insert(const_iterator position, T&& x);              // freestanding-deleted
+    constexpr iterator insert(const_iterator position, size_type n,         // freestanding-deleted
+                              const T& x);
+    template<class InputIterator>
+      constexpr iterator insert(const_iterator position,                    // freestanding-deleted
+                                InputIterator first, InputIterator last);
+    template<container-compatible-range<T> R>
+      constexpr iterator insert_range(const_iterator position, R&& rg);     // freestanding-deleted
+    constexpr iterator insert(const_iterator position,                      // freestanding-deleted
+                              initializer_list<T> il);
+    constexpr iterator erase(const_iterator position);
+    constexpr iterator erase(const_iterator first, const_iterator last);
+    constexpr void swap(inplace_vector& x)
+      noexcept(N == 0 || (is_nothrow_swappable_v<T> &&
+                          is_nothrow_move_constructible_v<T>));
+    constexpr void clear() noexcept;
+    friend constexpr bool operator==(const inplace_vector& x,
+                                     const inplace_vector& y);
+    friend constexpr synth-three-way-result<T>
+      operator<=>(const inplace_vector& x, const inplace_vector& y);
+    friend constexpr void swap(inplace_vector& x, inplace_vector& y)
+      noexcept(N == 0 || (is_nothrow_swappable_v<T> &&
+                          is_nothrow_move_constructible_v<T>))
+      { x.swap(y); }
+  };
+}
+```
+#### Constructors <a id="inplace.vector.cons">[[inplace.vector.cons]]</a>
+``` cpp
+constexpr explicit inplace_vector(size_type n);
+```
+*Preconditions:* `T` is *Cpp17DefaultInsertable* into `inplace_vector`.
+*Effects:* Constructs an `inplace_vector` with `n` default-inserted
+elements.
+*Complexity:* Linear in `n`.
+``` cpp
+constexpr inplace_vector(size_type n, const T& value);
+```
+*Preconditions:* `T` is *Cpp17CopyInsertable* into `inplace_vector`.
+*Effects:* Constructs an `inplace_vector` with `n` copies of `value`.
+*Complexity:* Linear in `n`.
+``` cpp
+template<class InputIterator>
+  constexpr inplace_vector(InputIterator first, InputIterator last);
+```
+*Effects:* Constructs an `inplace_vector` equal to the range \[`first`,
+`last`).
+*Complexity:* Linear in `distance(first, last)`.
+``` cpp
+template<container-compatible-range<T> R>
+  constexpr inplace_vector(from_range_t, R&& rg);
+```
+*Effects:* Constructs an `inplace_vector` with the elements of the range
+`rg`.
+*Complexity:* Linear in `ranges::distance(rg)`.
+#### Capacity <a id="inplace.vector.capacity">[[inplace.vector.capacity]]</a>
+``` cpp
+static constexpr size_type capacity() noexcept;
+static constexpr size_type max_size() noexcept;
+```
+*Returns:* `N`.
+``` cpp
+constexpr void resize(size_type sz);
+```
+*Preconditions:* `T` is *Cpp17DefaultInsertable* into `inplace_vector`.
+*Effects:* If `sz < size()`, erases the last `size() - sz` elements from
+the sequence. Otherwise, appends `sz - size()` default-inserted elements
+to the sequence.
+*Remarks:* If an exception is thrown, there are no effects on `*this`.
+``` cpp
+constexpr void resize(size_type sz, const T& c);
+```
+*Preconditions:* `T` is *Cpp17CopyInsertable* into `inplace_vector`.
+*Effects:* If `sz < size()`, erases the last `size() - sz` elements from
+the sequence. Otherwise, appends `sz - size()` copies of `c` to the
+sequence.
+*Remarks:* If an exception is thrown, there are no effects on `*this`.
+``` cpp
+static constexpr void reserve(size_type n);
+```
+*Effects:* None.
+*Throws:* `bad_alloc` if `n > capacity()` is `true`.
+``` cpp
+static constexpr void shrink_to_fit() noexcept;
+```
+*Effects:* None.
+#### Data <a id="inplace.vector.data">[[inplace.vector.data]]</a>
+``` cpp
+constexpr       T* data()       noexcept;
+constexpr const T* data() const noexcept;
+```
+*Returns:* A pointer such that \[`data()`, `data() + size()`) is a valid
+range. For a non-empty `inplace_vector`, `data() == addressof(front())`
+is `true`.
+*Complexity:* Constant time.
+#### Modifiers <a id="inplace.vector.modifiers">[[inplace.vector.modifiers]]</a>
+``` cpp
+constexpr iterator insert(const_iterator position, const T& x);
+constexpr iterator insert(const_iterator position, T&& x);
+constexpr iterator insert(const_iterator position, size_type n, const T& x);
+template<class InputIterator>
+  constexpr iterator insert(const_iterator position, InputIterator first, InputIterator last);
+template<container-compatible-range<T> R>
+  constexpr iterator insert_range(const_iterator position, R&& rg);
+constexpr iterator insert(const_iterator position, initializer_list<T> il);
+template<class... Args>
+  constexpr iterator emplace(const_iterator position, Args&&... args);
+template<container-compatible-range<T> R>
+  constexpr void append_range(R&& rg);
+```
+Let n be the value of `size()` before this call for the `append_range`
+overload, and `distance(begin, position)` otherwise.
+*Complexity:* Linear in the number of elements inserted plus the
+distance to the end of the vector.
+*Remarks:* If an exception is thrown other than by the copy constructor,
+move constructor, assignment operator, or move assignment operator of
+`T` or by any `InputIterator` operation, there are no effects.
+Otherwise, if an exception is thrown, then `size()` ≥ n and elements in
+the range `begin() + ``[``0, `n`)` are not modified.
+``` cpp
+constexpr reference push_back(const T& x);
+constexpr reference push_back(T&& x);
+template<class... Args>
+  constexpr reference emplace_back(Args&&... args);
+```
+*Returns:* `back()`.
+*Throws:* `bad_alloc` or any exception thrown by the initialization of
+the inserted element.
+*Complexity:* Constant.
+*Remarks:* If an exception is thrown, there are no effects on `*this`.
+``` cpp
+template<class... Args>
+  constexpr pointer try_emplace_back(Args&&... args);
+constexpr pointer try_push_back(const T& x);
+constexpr pointer try_push_back(T&& x);
+```
+Let `vals` denote a pack:
+- `std::forward<Args>(args)...` for the first overload,
+- `x` for the second overload,
+- `std::move(x)` for the third overload.
+*Preconditions:* `value_type` is *Cpp17EmplaceConstructible* into
+`inplace_vector` from `vals...`.
+*Effects:* If `size() < capacity()` is `true`, appends an object of type
+`T` direct-non-list-initialized with `vals...`. Otherwise, there are no
+effects.
+*Returns:* `nullptr` if `size() == capacity()` is `true`, otherwise
+`addressof(back())`.
+*Throws:* Nothing unless an exception is thrown by the initialization of
+the inserted element.
+*Complexity:* Constant.
+*Remarks:* If an exception is thrown, there are no effects on `*this`.
+``` cpp
+template<container-compatible-range<T> R>
+  constexpr ranges::borrowed_iterator_t<R> try_append_range(R&& rg);
+```
+*Preconditions:* `value_type` is *Cpp17EmplaceConstructible* into
+`inplace_vector` from
+`*ranges::begin(rg)`.
+*Effects:* Appends copies of initial elements in `rg` before `end()`,
+until all elements are inserted or `size() == capacity()` is `true`.
+Each iterator in the range `rg` is dereferenced at most once.
+*Returns:* The first iterator in the range `ranges::begin(rg)`+\[0, `n`)
+that was not inserted into `*this`, where `n` is the number of elements
+in `rg`.
+*Complexity:* Linear in the number of elements inserted.
+*Remarks:* Let n be the value of `size()` prior to this call. If an
+exception is thrown after the insertion of k elements, then `size()`
+equals n + k, elements in the range `begin() + ``[``0, `n`)` are not
+modified, and elements in the range `begin() + ``[`n`, `n + k`)`
+correspond to the inserted elements.
+``` cpp
+template<class... Args>
+  constexpr reference unchecked_emplace_back(Args&&... args);
+```
+*Preconditions:* `size() < capacity()` is `true`.
+*Effects:* Equivalent to:
+`return *try_emplace_back(std::forward<Args>(args)...);`
+``` cpp
+constexpr reference unchecked_push_back(const T& x);
+constexpr reference unchecked_push_back(T&& x);
+```
+*Preconditions:* `size() < capacity()` is `true`.
+*Effects:* Equivalent to:
+`return *try_push_back(std::forward<decltype(x)>(x));`
+``` cpp
+constexpr iterator erase(const_iterator position);
+constexpr iterator erase(const_iterator first, const_iterator last);
+constexpr void pop_back();
+```
+*Effects:* Invalidates iterators and references at or after the point of
+the erase.
+*Throws:* Nothing unless an exception is thrown by the assignment
+operator or move assignment operator of `T`.
+*Complexity:* The destructor of `T` is called the number of times equal
+to the number of the elements erased, but the assignment operator of `T`
+is called the number of times equal to the number of elements after the
+erased elements.
+#### Erasure <a id="inplace.vector.erasure">[[inplace.vector.erasure]]</a>
+``` cpp
+template<class T, size_t N, class U = T>
+  constexpr size_t erase(inplace_vector<T, N>& c, const U& value);
+```
+*Effects:* Equivalent to:
+``` cpp
+auto it = remove(c.begin(), c.end(), value);
+auto r = distance(it, c.end());
+c.erase(it, c.end());
+return r;
+```
+``` cpp
+template<class T, size_t N, class Predicate>
+  constexpr size_t erase_if(inplace_vector<T, N>& c, Predicate pred);
+```
+*Effects:* Equivalent to:
+``` cpp
+auto it = remove_if(c.begin(), c.end(), pred);
+auto r = distance(it, c.end());
+c.erase(it, c.end());
+return r;
+```

Diff to HTML by rtfpessoa