std::vector<T,Allocator>::insert - cppreference.com (original) (raw)

Inserts elements at the specified location in the container.

1. Inserts a copy of value before pos.

If any of the following conditions is satisfied, the behavior is undefined:

• T is not CopyAssignable.

1. Inserts value before pos, possibly using move semantics.

2. Inserts count copies of the value before pos.

If any of the following conditions is satisfied, the behavior is undefined:

• T is not CopyAssignable.

1. Inserts elements from range [first, last) before pos.

1. Inserts elements from initializer list ilist before pos.

Equivalent to insert(pos, ilist.begin(), ilist.end()).

If after the operation the new size() is greater than old capacity() a reallocation takes place, in which case all iterators (including the end() iterator) and all references to the elements are invalidated. Otherwise, only the iterators and references before the insertion point remain valid.

Contents

• 1 Parameters
• 2 Return value
• 3 Complexity
• 4 Exceptions
• 5 Example
• 6 Defect reports
• 7 See also

[edit] Parameters

[edit] Return value

1,2) Iterator pointing to the inserted value.

3-5) Iterator pointing to the first element inserted, or pos if no element is inserted.

[edit] Complexity

If reallocation happens, linear in the number of elements of the vector after insertion; otherwise, linear in the number of elements inserted plus std::distance(pos, end()).

[edit] Exceptions

If an exception is thrown other than by

• the copy constructor of T,

• the copy assignment operator of T,

• any InputIt operation,

these functions have no effect (strong exception safety guarantee).

[edit] Example

#include #include #include #include   namespace stq { void println(std::string_view rem, const std::vector& container) { std::cout << rem.substr(0, rem.size() - 2) << '['; bool first{true}; for (const int x : container) std::cout << (first ? first = false, "" : ", ") << x; std::cout << "]\n"; } }   int main() { std::vector c1(3, 100); stq::println("1. {}", c1);   auto pos = c1.begin(); pos = c1.insert(pos, 200); // overload (1) stq::println("2. {}", c1);   c1.insert(pos, 2, 300); // overload (3) stq::println("3. {}", c1);   // pos no longer valid, get a new one: pos = c1.begin();   std::vector c2(2, 400); c1.insert(std::next(pos, 2), c2.begin(), c2.end()); // overload (4) stq::println("4. {}", c1);   int arr[] = {501, 502, 503}; c1.insert(c1.begin(), arr, arr + std::size(arr)); // overload (4) stq::println("5. {}", c1);   c1.insert(c1.end(), {601, 602, 603}); // overload (5) stq::println("6. {}", c1); }

Output:

1. [100, 100, 100]
2. [200, 100, 100, 100]
3. [300, 300, 200, 100, 100, 100]
4. [300, 300, 400, 400, 200, 100, 100, 100]
5. [501, 502, 503, 300, 300, 400, 400, 200, 100, 100, 100]
6. [501, 502, 503, 300, 300, 400, 400, 200, 100, 100, 100, 601, 602, 603]

[edit] Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

[edit] See also