Namespaces
Variants
Views
Actions

std::inplace_vector

From cppreference.com
< cpp‎ | container
 
 
 
 
Defined in header <inplace_vector>
template<

    class T,
    std::size_t N

> struct inplace_vector;
(since C++26)

inplace_vector is a dynamically-resizable array with contiguous inplace storage. The elements of type T are stored and properly aligned within the object itself. The capacity of the internal storage is fixed at compile-time and is equal to N.

The elements are stored contiguously, which means that elements can be accessed not only through iterators or random-access operator[], but also using offsets to regular pointers to elements. A pointer to an element of an inplace_vector may be passed to any function that expects a pointer to an element of a C-array.

The inplace_vector models Container, ReversibleContainer, ContiguousContainer, and SequenceContainer, including most of the optional sequence container requirements, except that the push_front, emplace_front, pop_front, and prepend_range member functions are not provided.

For any positive N, std::inplace_vector<T, N>::iterator and std::inplace_vector<T, N>::const_iterator meet the ConstexprIterator requirements.

For any positive N, if T is not TriviallyCopyable or std::is_trivially_default_constructible_v<T> is false, then member functions of inplace_vector are not usable in constant expressions.

The specialization std::inplace_vector<T, 0> is TriviallyCopyable and is empty.

Any member function of std::inplace_vector<T, N> that would cause insertion beyond the capacity N throws std::bad_alloc.

The complexity of common operations on inplace_vectors is as follows:

  • Random access to an element via operator[] or at() – constant: 𝓞(1).
  • Insertion or removal of an element at the end – constant: 𝓞(1).
  • Insertion or removal of elements at the end – linear in the number of elements inserted/removed: 𝓞(n).
  • Insertion or removal of elements in the beginning or in the middle – linear in the number of elements inserted/removed plus the distance to the end of the vector: 𝓞(n).

Contents

[edit] Iterator invalidation

std::inplace_vector iterator invalidation guarantees differ from std::vector:

  • moving an inplace_vector invalidates all iterators;
  • swapping two inplace_vectors invalidates all iterators (during swap, the iterator will continue to point to the same array element, and may thus change its value).

The following member functions potentially invalidate iterators: operator=, assign, assign_range, clear, emplace, erase, insert, insert_range, pop_back, resize, and swap.

The following member functions potentially invalidate end iterator only: append_range, emplace_back, push_back, try_append_range, try_emplace_back, try_push_back, unchecked_emplace_back, and unchecked_push_back.

[edit] Template parameters

T - element type. Must be MoveConstructible and MoveAssignable.
N - capacity, i.e. the maximum number of elements in the inplace_vector (might be 0).

[edit] Member types

Type Definition
value_type T[edit]
size_type std::size_t[edit]
difference_type std::ptrdiff_t[edit]
reference value_type&[edit]
const_reference const value_type&[edit]
pointer value_type*[edit]
const_pointer const value_type*[edit]
iterator implementation-defined LegacyRandomAccessIterator and random_access_iterator to value_type[edit]
const_iterator implementation-defined LegacyRandomAccessIterator and random_access_iterator to const value_type[edit]
reverse_iterator std::reverse_iterator<iterator>[edit]
const_reverse_iterator std::reverse_iterator<const_iterator>[edit]

[edit] Member functions

constructs the inplace_vector
(public member function) [edit]
destructs the inplace_vector
(public member function) [edit]
assigns values to the container
(public member function) [edit]
assigns values to the container
(public member function) [edit]
assigns a range of values to the container
(public member function) [edit]
Element access
access specified element with bounds checking
(public member function) [edit]
access specified element
(public member function) [edit]
access the first element
(public member function) [edit]
access the last element
(public member function) [edit]
direct access to the underlying contiguous storage
(public member function) [edit]
Iterators
returns an iterator to the beginning
(public member function) [edit]
returns an iterator to the end
(public member function) [edit]
returns a reverse iterator to the beginning
(public member function) [edit]
returns a reverse iterator to the end
(public member function) [edit]
Size and capacity
checks whether the container is empty
(public member function) [edit]
returns the number of elements
(public member function) [edit]
[static]
returns the maximum possible number of elements
(public static member function) [edit]
[static]
returns the number of elements that can be held in currently allocated storage
(public static member function) [edit]
changes the number of elements stored
(public member function) [edit]
[static]
reserves storage
(public static member function) [edit]
reduces memory usage by freeing unused memory
(public static member function) [edit]
Modifiers
inserts elements
(public member function) [edit]
inserts a range of elements
(public member function) [edit]
constructs element in-place
(public member function) [edit]
constructs an element in-place at the end
(public member function) [edit]
tries to construct an element in-place at the end
(public member function) [edit]
unconditionally constructs an element in-place at the end
(public member function) [edit]
adds an element to the end
(public member function) [edit]
tries to add an element to the end
(public member function) [edit]
unconditionally adds an element to the end
(public member function) [edit]
removes the last element
(public member function) [edit]
adds a range of elements to the end
(public member function) [edit]
tries to add a range of elements to the end
(public member function) [edit]
clears the contents
(public member function) [edit]
erases elements
(public member function) [edit]
swaps the contents
(public member function) [edit]

[edit] Non-member functions

specializes the std::swap algorithm
(function template) [edit]
erases all elements satisfying specific criteria
(function template) [edit]
lexicographically compares the values of two inplace_vectors
(function template) [edit]

[edit] Notes

The number of elements in a inplace_vector may vary dynamically up to a fixed capacity because elements are stored within the object itself similarly to std::array. However, objects are initialized as they are inserted into inplace_vector unlike C arrays or std::array , which must construct all elements on instantiation.

inplace_vector is useful in environments where dynamic memory allocations are undesired.

Feature-test macro Value Std Feature
__cpp_lib_inplace_vector 202406L (C++26) std::inplace_vector: dynamically-resizable vector with fixed capacity inplace storage

[edit] Example

#include <algorithm>
#include <array>
#include <cassert>
#include <inplace_vector>
 
int main()
{
    std::inplace_vector<int, 4> v1{0, 1, 2};
    assert(v1.max_size() == 4);
    assert(v1.capacity() == 4);
    assert(v1.size() == 3);
    assert(std::ranges::equal(v1, std::array{0, 1, 2}));
    assert(v1[0] == 0);
    assert(v1.at(0) == 0);
    assert(v1.front() == 0);
    assert(*v1.begin() == 0);
    assert(v1.back() == 2);
    v1.push_back(3);
    assert(v1.back() == 3);
    assert(std::ranges::equal(v1, std::array{0, 1, 2, 3}));
    v1.resize(3);
    assert(std::ranges::equal(v1, std::array{0, 1, 2}));
    assert(v1.try_push_back(3) != nullptr);
    assert(v1.back() == 3);
    assert(v1.size() == 4);
    assert(v1.try_push_back(13) == nullptr); // no place
    assert(v1.back() == 3);
    assert(v1.size() == 4);
    v1.clear();
    assert(v1.size() == 0);
    assert(v1.empty());
}

[edit] See also

dynamic contiguous array
(class template) [edit]
(C++11)
fixed-sized inplace contiguous array
(class template) [edit]
double-ended queue
(class template) [edit]

[edit] External links

  inplace_vector — A reference implementation of P0843R14 (std::inplace_vector).
  static_vector — Boost.Container implements inplace vector as a standalone type with its own guarantees.
  fixed_vector — EASTL implements inplace vector via an extra template parameter.
  small_vector — Folly also implements inplace vector via an extra template parameter.
  stack_alloc — Howard Hinnant's Custom allocators that emulate std::inplace_vector on top of std::vector.