...
Unless otherwise specified (either explicitly or by defining a function in terms of other functions), invoking a container member function or passing a container as an argument to a library function shall not invalidate iterators to, or change the values of, objects within that container.
Note that while the C++ Standard allows references and pointers to be invalidated independently, this is not a secure operation because the object pointed to by the pointer may be different than expected. For instance, it is possible to retrieve a pointer to an element from a container, erase that element (invalidating references when destroying the underlying object), then insert a new element at the same location within the container causing the extant pointer to now point to a valid, but different than the original, object. Thus, any operation that invalidates a pointer or a reference should be treated as though it invalidates both pointers and references.
The following container functions can invalidate iterators, references, and /or pointers under certain circumstances:
| Class | Function | Iterators | References/Pointers | Notes | ||
|---|---|---|---|---|---|---|
std::deque | ||||||
insert(), emplace_front(), emplace_back(),emplace(), push_front(), push_back() | X | X | An insertion in the middle of the deque invalidates all the iterators and references to elements of the deque. An insertion at either end of the deque invalidates all the iterators to the deque but has no effect on the validity of references to elements of the deque. ([deque.modifiers], paragraph 1) | |||
erase(), pop_back(), resize() | X | X | An erase operation that erases the last element of a deque invalidates only the past-the-end iterator and all iterators and references to the erased elements. An erase operation that erases the first element of a deque but not the last element invalidates only the erased elements. An erase operation that erases neither the first element nor the last element of a deque invalidates the past-the-end iterator and all iterators and references to all the elements of the deque. ([deque.modifiers], paragraph 4) | |||
clear()X | X | X | Destroys all elements in the container. Invalidates all references, pointers, and iterators referring to the elements of the container and may invalidate the past-the-end iterator. ([sequence.reqmts], Table 100) | |||
std::forward_list | ||||||
erase_after(), pop_front(), resize() | X | X | erase_after shall invalidate only iterators and references to the erased elements. ([forwardlist.modifiers], paragraph 1) | |||
remove(), unique() | X | X | Invalidates only the iterators and references to the erased elements. ([forwardlist.ops], paragraph 12 & paragraph 16) | |||
clear()X | X | X | Destroys all elements in the container. Invalidates all references, pointers, and iterators referring to the elements of the container and may invalidate the past-the-end iterator. ([sequence.reqmts], Table 100) | |||
std::list | ||||||
erase(), pop_front(), pop_back(), clear(), remove(), remove_if(), unique() | X | X | Invalidates only the iterators and references to the erased elements. ([list.modifiers], paragraph 3 and [list.ops], paragraph 15 & paragraph 19) | |||
clear() | X | X | X | Destroys all elements in the container. Invalidates all references, pointers, and iterators referring to the elements of the container and may invalidate the past-the-end iterator. ([sequence.reqmts], Table 100) | ||
std::vector | ||||||
reserve() | X | X | X | After | ||
insert(), emplace_back(), emplace(), push_back() | X | X | Causes reallocation if the new size is greater than the old capacity. If no reallocation happens, all the iterators and references before the insertion point remain valid. ([vector.modifiers], paragraph 1). All iterators and references after the insertion point are invalidated. | |||
erase(), pop_back(), resize() | X | X | Invalidates iterators and references at or after the point of the erase. ([vector.modifiers], paragraph 3) | |||
clear() | X | X | X | Destroys all elements in the container. Invalidates all references, pointers, and iterators referring to the elements of the container and may invalidate the past-the-end iterator. ([sequence.reqmts], Table 100) | ||
std::set, std::multiset, std::map, std::multimap | ||||||
erase(), clear() | X | X | Invalidates only iterators and references to the erased elements. ([associative.reqmts], paragraph 9) | |||
| ||||||
erase(), clear() | X | X | Invalidates only iterators and references to the erased elements. ([unord.req], paragraph 14) | |||
insert(), emplace() | X | The | ||||
rehash(), reserve() | X | Rehashing invalidates iterators, changes ordering between elements, and changes which buckets the elements appear in but does not invalidate pointers or references to elements. ([unord.req], paragraph 9) | ||||
std::valarray | resize() | X | X | Resizing invalidates all pointers and references to elements in the array. ([valarray.members], paragraph 12) |
...