CKTIS / C++
std::vector::insert — insert elements into a vector
Insert a value, repeated copies, an initializer list, or an iterator range before a chosen position. Use the returned iterator and know which existing handles become invalid.
Version: ISO C++23; implementation support may vary
Syntax
/* <vector>, public members of std::vector<T, Allocator> in C++23 */
constexpr iterator insert(const_iterator pos, const T& value);
constexpr iterator insert(const_iterator pos, T&& value);
constexpr iterator insert(const_iterator pos, size_type count, const T& value);
template<class InputIt>
constexpr iterator insert(const_iterator pos, InputIt first, InputIt last);
constexpr iterator insert(const_iterator pos, std::initializer_list<T> values);std::vector::insert is a member function from <vector> that modifies the receiving vector v by inserting before pos. The const_iterator parameter must be a valid position in v: v.cbegin() inserts at the front, and v.cend() appends. The return type is iterator; it points to the first inserted element, or represents the same position as pos if nothing was inserted. Do not dereference the result if it equals v.end().
insert(pos, value) with const T& copies one value, while the T&& overload allows moving from an rvalue. insert(pos, count, value) inserts count copies, and insert(pos, {a, b}) inserts the list elements in order. T must meet the selected overload's requirements for construction and assignment; do not assume the copying overloads work with a move-only type.
insert(pos, first, last) reads a valid half-open range [first, last), excluding last. Ordinary iterators from another vector copy its elements; wrapping both endpoints with std::make_move_iterator allows moves from mutable source elements when the type supports them. Never pass source-range iterators from the destination vector: that is undefined behavior even if capacity is sufficient. Copy the range to a separate container first if necessary. insert_range(pos, range) is a separate C++23 member; availability depends on the library implementation.
If the new size exceeds the old capacity, reallocation invalidates all existing destination iterators, pointers, and references, including the old end(). For a nonempty insertion without reallocation, only handles strictly before the insertion point stay valid; the old end() is still invalidated. Use the returned iterator or obtain fresh iterators. The cost is linear in the resulting size with reallocation, or in the number inserted plus the distance from pos to the end without it.
Do not assume every exception leaves the vector unchanged. Allocation failure leaves it unchanged, but there is no blanket no-effects guarantee for exceptions from element copying, moving or assignment, or from input-iterator operations. A single insertion at the end leaves the vector unchanged on exception if T is Cpp17CopyInsertable into that vector or std::is_nothrow_move_constructible_v<T> is true. Otherwise, if the move constructor of a non-Cpp17CopyInsertable type throws, the effects are unspecified.
Examples
#include <iostream>
#include <vector>
int main() {
std::vector<int> metrics{10, 40};
const std::vector<int> batch{20, 30};
const auto first = metrics.insert(metrics.cbegin() + 1,
batch.begin(), batch.end());
std::cout << "first inserted: " << *first << '\n';
std::cout << "metrics:";
for (int value : metrics) {
std::cout << ' ' << value;
}
std::cout << "\nsize: " << metrics.size() << '\n';
}Result
first inserted: 20 metrics: 10 20 30 40 size: 4
`batch` is a separate vector. Its elements go before `40`; `*first` is `20` and `metrics.size()` is `4`. The output does not depend on whether reallocation occurs.
Related lessons
- C++ · Lesson 14 · Advanced · Version: 3