View source for cpp/container/inplace vector

{{cpp/title|inplace_vector}}
{{cpp/container/inplace_vector/navbar}}
{{ddcl|header=inplace_vector|since=c++26|
template<
    class T,
    std::size_t N
> struct inplace_vector;
}}

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

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

The {{tt|inplace_vector}} models {{named req|Container}}, {{named req|ReversibleContainer}}, {{named req|ContiguousContainer}}, and {{named req|SequenceContainer}}, including most of the [[cpp/named_req/SequenceContainer#Optional operations|optional sequence container requirements]], except that the {{tt|push_front}}, {{tt|emplace_front}}, {{tt|pop_front}}, and {{tt|prepend_range}} member functions are not provided.

For any {{tt|N}}, {{c|std::inplace_vector<T, N>::iterator}} and {{c|std::inplace_vector<T, N>::const_iterator}} meet the {{named req|ConstexprIterator}} requirements.

If {{c|N > 0}} and {{c|std::is_trivial_v<T>}} is {{c|false}}, then member functions of {{tt|inplace_vector}} are not {{lsd|cpp/language/constant expression#Usable in constant expressions}}.

The specialization {{c|std::inplace_vector<T, 0>}} is a {{named req|TrivialType}} and is empty.

Any member function of {{c|std::inplace_vector<T, N>}} that would cause insertion beyond the capacity {{tt|N}} throws {{lc|std::bad_alloc}}.

The complexity of common operations on {{tt|inplace_vector}}s is as follows:
* Random access to an element via {{rlt|operator at|operator[]}} or {{rlt|at|at()}} &ndash; constant: {{math|𝓞(1)}}.
* Insertion or removal of an element at the end &ndash; constant: {{math|𝓞(1)}}.
* Insertion or removal of elements at the end &ndash; linear in the number of elements inserted: {{math|𝓞(n)}}.
* Insertion or removal of elements in the beginning or in the middle &ndash; linear in the number of elements inserted/removed plus the distance to the end of the vector: {{math|𝓞(n)}}.

===Iterator invalidation===
{{tt|std::inplace_vector}} iterator invalidation guarantees differ from {{lc|std::vector}}:
* moving an {{tt|inplace_vector}} invalidates all iterators;
* swapping two {{tt|inplace_vector}}s 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:
{{rlt|operator{{=}}}}, 
{{rlt|assign}}, 
{{rlt|assign_range}}, 
{{rlt|clear}}, 
{{rlt|emplace}}, 
{{rlt|erase}}, 
{{rlt|insert}}, 
{{rlt|insert_range}}, 
{{rlt|pop_back}}, 
{{rlt|resize}}, and 
{{rlt|swap}}.

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

===Template parameters===
{{par begin}}
{{par|T|element type. Must be {{named req|MoveConstructible}} and {{named req|MoveAssignable}}.}}
{{par|N|capacity, i.e. the maximum number of elements in the {{tt|inplace_vector}} (might be {{c|0}}).}}
{{par end}}

===Member types===
{{dsc begin}}
{{dsc hitem|Member type|Definition}}
{{dsc inc|cpp/container/dsc value_type|inplace_vector}}
{{dsc inc|cpp/container/dsc size_type|inplace_vector}}
{{dsc inc|cpp/container/dsc difference_type|inplace_vector}}
{{dsc inc|cpp/container/dsc reference|inplace_vector}}
{{dsc inc|cpp/container/dsc const_reference|inplace_vector}}
{{dsc inc|cpp/container/dsc pointer|inplace_vector}}
{{dsc inc|cpp/container/dsc const_pointer|inplace_vector}}
{{dsc inc|cpp/container/dsc iterator|inplace_vector}}
{{dsc inc|cpp/container/dsc const_iterator|inplace_vector}}
{{dsc inc|cpp/container/dsc reverse_iterator|inplace_vector}}
{{dsc inc|cpp/container/dsc const_reverse_iterator|inplace_vector}}
{{dsc end}}

===Member functions===
{{dsc begin}}
{{dsc inc|cpp/container/dsc constructor|inplace_vector}}
{{dsc inc|cpp/container/dsc destructor|inplace_vector}}
{{dsc inc|cpp/container/dsc operator{{=}}|inplace_vector}}
{{dsc inc|cpp/container/dsc assign|inplace_vector}}
{{dsc inc|cpp/container/dsc assign_range|inplace_vector}}

{{dsc h2|Element access}}
{{dsc inc|cpp/container/dsc at|inplace_vector}}
{{dsc inc|cpp/container/dsc operator_at|inplace_vector}}
{{dsc inc|cpp/container/dsc front|inplace_vector}}
{{dsc inc|cpp/container/dsc back|inplace_vector}}
{{dsc inc|cpp/container/dsc data|inplace_vector}}

{{dsc h2|Iterators}}
{{dsc inc|cpp/container/dsc begin|inplace_vector}}
{{dsc inc|cpp/container/dsc end|inplace_vector}}
{{dsc inc|cpp/container/dsc rbegin|inplace_vector}}
{{dsc inc|cpp/container/dsc rend|inplace_vector}}

{{dsc h2|Size and capacity}}
{{dsc inc|cpp/container/dsc empty|inplace_vector}}
{{dsc inc|cpp/container/dsc size|inplace_vector}}
{{dsc inc|cpp/container/dsc max_size|inplace_vector}}
{{dsc inc|cpp/container/dsc capacity|inplace_vector}}
{{dsc inc|cpp/container/dsc resize|inplace_vector}}
{{dsc inc|cpp/container/dsc reserve|inplace_vector}}
{{dsc inc|cpp/container/dsc shrink_to_fit|inplace_vector}}

{{dsc h2|Modifiers}}
{{dsc inc|cpp/container/dsc insert|inplace_vector}}
{{dsc inc|cpp/container/dsc insert_range|inplace_vector}}
{{dsc inc|cpp/container/dsc emplace|inplace_vector}}
{{dsc inc|cpp/container/dsc emplace_back|inplace_vector}}
{{dsc inc|cpp/container/dsc try_emplace_back|inplace_vector}}
{{dsc inc|cpp/container/dsc unchecked_emplace_back|inplace_vector}}
{{dsc inc|cpp/container/dsc push_back|inplace_vector}}
{{dsc inc|cpp/container/dsc try_push_back|inplace_vector}}
{{dsc inc|cpp/container/dsc unchecked_push_back|inplace_vector}}
{{dsc inc|cpp/container/dsc pop_back|inplace_vector}}
{{dsc inc|cpp/container/dsc append_range|inplace_vector}}
{{dsc inc|cpp/container/dsc try_append_range|inplace_vector}}
{{dsc inc|cpp/container/dsc clear|inplace_vector}}
{{dsc inc|cpp/container/dsc erase|inplace_vector}}
{{dsc inc|cpp/container/dsc swap|inplace_vector}}
{{dsc end}}

===Non-member functions===
{{dsc begin}}
{{dsc inc|cpp/container/dsc swap2|inplace_vector}}
{{dsc inc|cpp/container/dsc erase seq|inplace_vector}}
{{dsc inc|cpp/container/dsc operator cmp|inplace_vector}}
{{dsc end}}

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

{{tt|inplace_vector}} is useful in environments where dynamic memory allocations are undesired.

{{feature test macro|__cpp_lib_inplace_vector|std=C++26|value=202406L|{{tt|std::inplace_vector}}: dynamically-resizable vector with fixed capacity inplace storage}}

===Example===
{{example
|code=
#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());
}
}}

===See also===
{{dsc begin}}
{{dsc inc|cpp/container/dsc vector}}
{{dsc inc|cpp/container/dsc array}}
{{dsc inc|cpp/container/dsc deque}}
{{dsc end}}

===External links===
{{elink begin}}
{{elink|[https://godbolt.org/z/5P78aG5xE {{tt|inplace_vector}}] &mdash; A reference implementation of {{stddoc|P0843R14}} ({{tt|std::inplace_vector}}).}}
{{elink|[https://www.boost.org/doc/libs/release/doc/html/container/non_standard_containers.html#container.non_standard_containers.static_vector {{tt|static_vector}}] &mdash; Boost.Container implements inplace vector as a standalone type with its own guarantees.}}
{{elink|[https://github.com/questor/eastl/blob/master/fixed_vector.h#L71 {{tt|fixed_vector}}] &mdash; EASTL implements inplace vector via an extra template parameter.}}
{{elink|[https://github.com/facebook/folly/blob/master/folly/docs/small_vector.md {{tt|small_vector}}] &mdash; Folly also implements inplace vector via an extra template parameter.}}
{{elink|[https://howardhinnant.github.io/stack_alloc.html {{tt|stack_alloc}}] &mdash; Howard Hinnant's Custom allocators that emulate {{tt|std::inplace_vector}} on top of {{lc|std::vector}}.}}
{{elink end}}

{{langlinks|de|es|fr|it|ja|pl|pt|ru|zh}}