Difference between revisions of "cpp/container/inplace vector"

Revision as of 10:39, 10 August 2024

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 (that is, the elements of type T are stored and properly aligned within the object itself) and with fixed at compile-time capacity N.

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

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

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

For any N > 0, if std::is_trivial_v<T> is false, then no std::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 std::bad_alloc.

Let V denote a specialization of inplace_vector<T, N>. If N is zero, then V is both trivial and empty. Otherwise:

If std::is_trivially_copy_constructible_v<T> is true, then V has a trivial copy constructor.
If std::is_trivially_move_constructible_v<T> is true, then V has a trivial move constructor.
If std::is_trivially_destructible_v<T> is true, then:
- V has a trivial destructor.
- If std::is_trivially_copy_constructible_v<T> && std::is_trivially_copy_assignable_v<T> is true, then V has a trivial copy assignment operator.
- If std::is_trivially_move_constructible_v<T> && std::is_trivially_move_assignable_v<T> is true, then V has a trivial move assignment operator.

Member 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]

Member functions

(constructor)	constructs the `inplace_vector` (public member function) [edit]
(destructor)	destructs the `inplace_vector` (public member function) [edit]
operator=	assigns values to the container (public member function) [edit]
assign	assigns values to the container (public member function) [edit]
assign_range	assigns a range of values to the container (public member function) [edit]
Element access
at	access specified element with bounds checking (public member function) [edit]
operator[]	access specified element (public member function) [edit]
front	access the first element (public member function) [edit]
back	access the last element (public member function) [edit]
data	direct access to the underlying contiguous storage (public member function) [edit]
Iterators
begincbegin	returns an iterator to the beginning (public member function) [edit]
endcend	returns an iterator to the end (public member function) [edit]
rbegincrbegin	returns a reverse iterator to the beginning (public member function) [edit]
rendcrend	returns a reverse iterator to the end (public member function) [edit]
Size and capacity
empty	checks whether the container is empty (public member function) [edit]
size	returns the number of elements (public member function) [edit]
max_size [static]	returns the maximum possible number of elements (public static member function) [edit]
capacity [static]	returns the number of elements that can be held in currently allocated storage (public static member function) [edit]
resize	changes the number of elements stored (public member function) [edit]
reserve [static]	reserves storage (public static member function) [edit]
shrink_to_fit [static]	reduces memory usage by freeing unused memory (public static member function) [edit]
Modifiers
insert	inserts elements (public member function) [edit]
insert_range	inserts a range of elements (public member function) [edit]
emplace	constructs element in-place (public member function) [edit]
emplace_back	constructs an element in-place at the end (public member function) [edit]
try_emplace_back	tries to construct an element in-place at the end (public member function) [edit]
unchecked_emplace_back	unconditionally constructs an element in-place at the end (public member function) [edit]
push_back	adds an element to the end (public member function) [edit]
try_push_back	tries to add an element to the end (public member function) [edit]
unchecked_push_back	unconditionally adds an element to the end (public member function) [edit]
pop_back	removes the last element (public member function) [edit]
append_range	adds a range of elements to the end (public member function) [edit]
try_append_range	tries to add a range of elements to the end (public member function) [edit]
resize	changes the number of elements stored (public member function) [edit]
clear	clears the contents (public member function) [edit]
erase	erases elements (public member function) [edit]
swap	swaps the contents (public member function) [edit]

Non-member functions

std::swap(std::inplace_vector) (C++26)	specializes the std::swap algorithm (function template) [edit]
erase(std::inplace_vector)erase_if(std::inplace_vector) (C++26)	erases all elements satisfying specific criteria (function template) [edit]
operator==operator<=> (C++26)	lexicographically compares the values of two `inplace_vector`s (function template) [edit]

Notes

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

Example

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.

@@ Line 8: / Line 8: @@
 }}
-{{tt|inplace_vector}} is a dynamically-resizable array with contiguous inplace storage (that is, the elements of type {{tt|T}} are stored within the object itself) and with fixed at compile-time capacity {{tt|N}}.
+{{tt|inplace_vector}} is a dynamically-resizable array with contiguous inplace storage (that is, the elements of type {{tt|T}} are stored and properly aligned within the object itself) and with fixed at compile-time capacity {{tt|N}}.
 {{tt|inplace_vector}} is useful in environments where dynamic memory allocations are undesired.
-<!--DONE-->
+The {{tt|inplace_vector}} satisfies the requirements of {{named req|Container}}, {{named req|ReversibleContainer}}, {{named req|ContiguousContainer}}, and of a {{named req|SequenceContainer}}, including most of the [[cpp/named_req/SequenceContainer#Optional operations|optional sequence container requirements]], except that the {{tt|push_front}}, {{tt|prepend_range}}, {{tt|pop_front}}, and {{tt|emplace_front}} member functions are not provided.
-{{todo}}
-<!--TODO: Below is a mere copy from std::array. REPLACE!
-{{tt|std::inplace_vector}} is a container that encapsulates fixed size inplace_vectors.
+For any {{tt|N}}, {{c/core|std::inplace_vector<T, N>::iterator}} and {{c/core|std::inplace_vector<T, N>::const_iterator}} meet the constexpr iterator requirements.
-This container is an aggregate type with the same semantics as a struct holding a [[cpp/language/inplace_vector|C-style inplace_vector]] {{c|T[N]}} as its only non-static data member. Unlike a C-style inplace_vector, it doesn't decay to {{c|T*}} automatically. As an aggregate type, it can be initialized with [[cpp/language/aggregate initialization|aggregate-initialization]] given at most {{tt|N}} initializers that are convertible to {{tt|T}}: {{c|1=std::inplace_vector<int, 3> a = {1, 2, 3};}}.
+For any {{c|N > 0}}, if {{c/core|std::is_trivial_v<T>}} is {{c|false}}, then no {{c/core|std::inplace_vector<T, N>}} member functions are <!--TODO: add link-->usable in constant expressions.
-The struct combines the performance and accessibility of a C-style inplace_vector with the benefits of a standard container, such as knowing its own size, supporting assignment, random access iterators, etc.
+Any member function of {{c/core|inplace_vector<T, N>}} that would cause the size to exceed {{tt|N}} throws an exception of type {{lc|std::bad_alloc}}.
-{{tt|std::inplace_vector}} satisfies the requirements of {{named req|Container}} and {{named req|ReversibleContainer}} except that default-constructed inplace_vector is not empty and that the complexity of swapping is linear, {{rev inl|since=c++17|satisfies the requirements of {{named req|ContiguousContainer}},}} and partially satisfies the requirements of {{named req|SequenceContainer}}.
+Let {{tt|V}} denote a specialization of {{c/core|inplace_vector<T, N>}}.
+If {{tt|N}} is zero, then {{tt|V}} is both trivial and empty.
-There is a special case for a zero-length inplace_vector ({{tt|1=N == 0}}). In that case, {{c|
+Otherwise:
-=inplace_vector.begin() == inplace_vector.end()}}, which is some unique value. The effect of calling {{c|front()}} or {{c|back()}} on a zero-sized inplace_vector is undefined.
+* If {{c/core|std::is_trivially_copy_constructible_v<T>}} is {{c|true}}, then {{tt|V}} has a trivial copy constructor.
+* If {{c/core|std::is_trivially_move_constructible_v<T>}} is {{c|true}}, then {{tt|V}} has a trivial move constructor.
-An inplace_vector can also be used as a tuple of {{tt|N}} elements of the same type.
+* If {{c/core|std::is_trivially_destructible_v<T>}} is {{c|true}}, then:
--->
+** {{tt|V}} has a trivial destructor.
+** If {{c|std::is_trivially_copy_constructible_v<T> && std::is_trivially_copy_assignable_v<T>}} is {{c|true}}, then {{tt|V}} has a trivial copy assignment operator.
+** If {{c|std::is_trivially_move_constructible_v<T> && std::is_trivially_move_assignable_v<T>}} is {{c|true}}, then {{tt|V}} has a trivial move assignment operator.
 ===Iterator invalidation===
 {{todo}}
-<!--TODO: A COPY from std::array
-As a rule, iterators to an inplace_vector are never invalidated throughout the lifetime of the inplace_vector. One should take note, however, that during {{rl|swap}}, the iterator will continue to point to the same inplace_vector element, and will thus change its value.
--->
 ===Template parameters===
@@ Line 145: / Line 142: @@
 ===External links===
 {{elink begin}}
-{{elink|[https://www.boost.org/doc/libs/release/doc/html/boost/container/static_vector.html Boost.Container: {{tt|static_vector}}] implements inplace vector as a standalone type with its own guarantees.}}
+{{elink|[https://godbolt.org/z/5P78aG5xE {{tt|inplace_vector}}] &mdash; A reference implementation of {{stddoc|P0843R14}} ({{tt|std::inplace_vector}}).}}
-{{elink|[https://github.com/questor/eastl/blob/master/fixed_vector.h#L71 EASTL: {{tt|fixed_vector}}] implements inplace vector via an extra template parameter.}}
+{{elink|[https://www.boost.org/doc/libs/release/doc/html/boost/container/static_vector.html {{tt|static_vector}}] &mdash; Boost.Container implements inplace vector as a standalone type with its own guarantees.}}
-{{elink|[https://github.com/facebook/folly/blob/master/folly/docs/small_vector.md Folly: {{tt|small_vector}}] also implements inplace vector via an extra template parameter.}}
+{{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://godbolt.org/z/5P78aG5xE Compiler Explorer] &mdash; A reference implementation of {{stddoc|P0843R14}} ({{tt|std::inplace_vector}}).}}
+{{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}}

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Metaprogramming library (C++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (C++17)
Regular expressions library (C++11)
Concurrency support library (C++11)
Execution support library (C++26)
Technical specifications
Symbols index
External libraries

Sequence
array (C++11)
vector
vector<bool>
inplace_vector (C++26)
deque
forward_list (C++11)
list
Associative
set
multiset
map
multimap
Unordered associative
unordered_set (C++11)
unordered_multiset (C++11)
unordered_map (C++11)
unordered_multimap (C++11)
Adaptors
stack
queue
priority_queue
flat_set (C++23)
flat_multiset (C++23)
flat_map (C++23)
flat_multimap (C++23)
Views
span (C++20)
mdspan (C++23)
Tables
Iterator invalidation
Member function table
Non-member function table

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

cppreference.com

Namespaces

Variants

Views

Actions

Difference between revisions of "cpp/container/inplace vector"

Revision as of 10:39, 10 August 2024

Contents

Iterator invalidation

Template parameters

Member types

Member functions

Element access

Iterators

Size and capacity

Modifiers

Non-member functions

Notes

Example

See also

External links

Navigation

Toolbox

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