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

Inserts elements at the specified location in the container.

1. Inserts a copy of value before pos.

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

If T is not MoveInsertable into list, the behavior is undefined.

1. 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.

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

• first or last are iterators into *this.

1. Inserts elements from initializer list ilist before pos.

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

No iterators or references are invalidated.

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

Linear in the number of elements inserted.

[edit] Exceptions

If an exception is thrown for any reason, 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::list& 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::list 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);   // reset pos to the begin: pos = c1.begin();   std::list 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