std::vector::insert

single element (1)	iterator insert (iterator position, const value_type& val);
fill (2)	void insert (iterator position, size_type n, const value_type& val);
range (3)	template <class InputIterator> void insert (iterator position, InputIterator first, InputIterator last);

single element (1)

iterator insert (iterator position, const value_type& val);

fill (2)

    void insert (iterator position, size_type n, const value_type& val);

range (3)

template <class InputIterator>    void insert (iterator position, InputIterator first, InputIterator last);

single element (1)	iterator insert (const_iterator position, const value_type& val);
fill (2)	iterator insert (const_iterator position, size_type n, const value_type& val);
range (3)	template <class InputIterator>iterator insert (const_iterator position, InputIterator first, InputIterator last);
move (4)	iterator insert (const_iterator position, value_type&& val);
initializer list (5)	iterator insert (const_iterator position, initializer_list<value_type> il);

Insert elements

The vector is extended by inserting new elements before the element at the specified position, effectively increasing the container size by the number of elements inserted.

This causes an automatic reallocation of the allocated storage space if -and only if- the new vector size surpasses the current vector capacity.

Because vectors use an array as their underlying storage, inserting elements in positions other than the vector end causes the container to relocate all the elements that were after position to their new positions. This is generally an inefficient operation compared to the one performed for the same operation by other kinds of sequence containers (such as list or forward_list).

The parameters determine how many elements are inserted and to which values they are initialized:

Parameters

position: Position in the vector where the new elements are inserted.
iterator is a member type, defined as a random access iterator type that points to elements.
val: Value to be copied (or moved) to the inserted elements.
Member type value_type is the type of the elements in the container, defined in deque as an alias of its first template parameter (T).
n: Number of elements to insert. Each element is initialized to a copy of val.
Member type size_type is an unsigned integral type.
first, last: Iterators specifying a range of elements. Copies of the elements in the range [first,last) are inserted at position (in the same order).
Notice that the range includes all the elements between first and last, including the element pointed by first but not the one pointed by last.
The function template argument InputIterator shall be an input iterator type that points to elements of a type from which value_type objects can be constructed.
il: An initializer_list object. Copies of these elements are inserted at position (in the same order).
These objects are automatically constructed from initializer list declarators.
Member type value_type is the type of the elements in the container, defined in vector as an alias of its first template parameter (T).

Return value

An iterator that points to the first of the newly inserted elements.

Member type iterator is a random access iterator type that points to elements.

If reallocations happen, the storage is allocated using the container's allocator, which may throw exceptions on failure (for the default allocator, bad_alloc is thrown if the allocation request does not succeed).

Example

// inserting into a vector
#include <iostream>
#include <vector>

int main ()
{
  std::vector<int> myvector (3,100);
  std::vector<int>::iterator it;

  it = myvector.begin();
  it = myvector.insert ( it , 200 );

  myvector.insert (it,2,300);

  // "it" no longer valid, get a new one:
  it = myvector.begin();

  std::vector<int> anothervector (2,400);
  myvector.insert (it+2,anothervector.begin(),anothervector.end());

  int myarray [] = { 501,502,503 };
  myvector.insert (myvector.begin(), myarray, myarray+3);

  std::cout << "myvector contains:";
  for (it=myvector.begin(); it<myvector.end(); it++)
    std::cout << ' ' << *it;
  std::cout << '\n';

  return 0;
}

Output:

myvector contains: 501 502 503 300 300 400 400 200 100 100 100

Complexity

Linear on the number of elements inserted (copy/move construction) plus the number of elements after position (moving).

Additionally, if InputIterator in the range insert (3) is not at least of a forward iterator category (i.e., just an input iterator) the new capacity cannot be determined beforehand and the insertion incurs in additional logarithmic complexity in size (reallocations).

If a reallocation happens, the reallocation is itself up to linear in the entire size at the moment of the reallocation.

Iterator validity

If a reallocation happens, all iterators, pointers and references related to the container are invalidated.
Otherwise, only those pointing to position and beyond are invalidated, with all iterators, pointers and references to elements before position guaranteed to keep referring to the same elements they were referring to before the call.

Data races

All copied elements are accessed.
The container is modified.
If a reallocation happens, all contained elements are modified.
Otherwise, none of the elements before position is accessed, and concurrently accessing or modifying them is safe (although see iterator validity above).

Exception safety

If the operation inserts a single element at the end, and no reallocations happen, there are no changes in the container in case of exception (strong guarantee). In case of reallocations, the strong guarantee is also given in this case if the type of the elements is either copyable or no-throw moveable.
Otherwise, the container is guaranteed to end in a valid state (basic guarantee).
If allocator_traits::construct is not supported with the appropriate arguments for the element constructions, or if an invalid position or range is specified, it causes undefined behavior.

member functions

non-member overloads