std::inplace_vector
<inplace_vector>
class T,
std::size_t N
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.
The specialization std::inplace_vector<T, 0> is TriviallyCopyable and is empty. std::is_trivially_default_constructible_v <std::inplace_vector<T, 0>> is also true.
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[]orat()– constant: O(1). - Insertion or removal of an element at the end – constant: O(1).
- Insertion or removal of elements at the end – linear in the number of elements inserted/removed: O(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: O(n).
Contents
[edit] Iterator invalidation
std::inplace_vector iterator invalidation guarantees differ from std::vector :
- moving an
inplace_vectorinvalidates 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
inplace_vector (might be 0).
[edit] Member types
iterator
implementation-defined LegacyRandomAccessIterator and random_access_iterator to value_type[edit]
const_iterator
implementation-defined LegacyRandomAccessIterator , ConstexprIterator (since C++26) and random_access_iterator to const value_type[edit]
[edit] Member functions
Element access
Iterators
Size and capacity
(public static member function) [edit]
Modifiers
[edit] Non-member functions
[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
|
__cpp_lib_constexpr_inplace_vector |
202502L |
(C++26) | constexpr std::inplace_vector for non-trivial element types
|
[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
[edit] External links
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 .