23 Containers library [containers]

23.3 Sequence containers [sequences]

23.3.14 Class template inplace_vector [inplace.vector]

23.3.14.1 Overview [inplace.vector.overview]

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.

For any

N > 0

, if is_trivial_v<T> is false, then no inplace_vector<T, N> member functions are usable in constant expressions.

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 both trivial and empty.

Otherwise:

(6.1)
If is_trivially_copy_constructible_v<T> is true, then IV has a trivial copy constructor.
(6.2)
If is_trivially_move_constructible_v<T> is true, then IV has a trivial move constructor.
(6.3)
If is_trivially_destructible_v<T> is true, then:
- (6.3.1)
  IV has a trivial destructor.
- (6.3.2)
  If is_trivially_copy_constructible_v<T> && is_trivially_copy_assignable_v<T> is true, then IV has a trivial copy assignment operator.
- (6.3.3)
  If is_trivially_move_constructible_v<T> && is_trivially_move_assignable_v<T> is true, then IV has a trivial move assignment operator.

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; // see [container.requirements] using const_iterator = implementation-defined; // 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], size/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; constexpr friend bool operator==(const inplace_vector& x, const inplace_vector& y); constexpr friend synth-three-way-result<T> operator<=>(const inplace_vector& x, const inplace_vector& y); constexpr friend 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); } }; };

23.3.14.2 Constructors [inplace.vector.cons]

🔗

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.

🔗

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.

🔗

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).

🔗

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).

23.3.14.3 Size and capacity [inplace.vector.capacity]

🔗

static constexpr size_type capacity() noexcept;
static constexpr size_type max_size() noexcept;

Returns: N.

🔗

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.

🔗

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.

23.3.14.4 Data [inplace.vector.data]

🔗

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.

23.3.14.5 Modifiers [inplace.vector.modifiers]

🔗

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.

🔗

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.

🔗

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:

(8.1)
std::forward<Args>(args)... for the first overload,
(8.2)
x for the second overload,
(8.3)
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.

🔗

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: An iterator pointing to the first element of rg that was not inserted into *this, or ranges::end(rg) if no such element exists.

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.

🔗

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)...);

🔗

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));

🔗

static constexpr void reserve(size_type n);

Effects: None.

Throws: bad_alloc if n > capacity() is true.

🔗

static constexpr void shrink_to_fit() noexcept;

Effects: None.

🔗

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.

23.3.14.6 Erasure [inplace.vector.erasure]

🔗

template<class T, size_t N, class U = T>
  constexpr size_t erase(inplace_vector<T, N>& c, const U& value);

Effects: Equivalent to: auto it = remove(c.begin(), c.end(), value); auto r = distance(it, c.end()); c.erase(it, c.end()); return r;

🔗

template<class T, size_t N, class Predicate>
  constexpr size_t erase_if(inplace_vector<T, N>& c, Predicate pred);

Effects: Equivalent to: auto it = remove_if(c.begin(), c.end(), pred); auto r = distance(it, c.end()); c.erase(it, c.end()); return r;