iterator insert ( iterator position, const T& x );
    void insert ( iterator position, size_type n, const T& x );
template <class InputIterator>
    void insert ( iterator position, InputIterator first, InputIterator last );

Insert elements

The vector is extended by inserting new elements before the element at position.

This effectively increases the vector size, which causes an automatic reallocation of the allocated storage space if, and only if, the new vector size surpases the current vector capacity. Reallocations in vector containers invalidate all previously obtained iterators, references and pointers.

Because vectors keep an array format, insertions on positions other than the vector end are performed by moving all the elements between position and the end of the vector to their new positions, and then inserting the new element(s), which may not be a method as efficient as the insertion in other kinds of sequence containers (deque, 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.

x

Value to be used to initialize the inserted elements.
T is the first template parameter (the type of the elements stored in the vector).

n

Number of elements to insert. Each element is initialized to the value specified in x.
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 position.
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 template type can be any type of input iterator.

Return value

If reallocations happen, they are performed using Allocator::allocate(), which may throw exceptions (for the default allocator, bad_alloc is thrown if the allocation request does not succeed).

Example

// inserting into a vector
#include <iostream>
#include <vector>
using namespace std;

int main ()
{
  vector<int> myvector (3,100);
  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();

  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);

  cout << "myvector contains:";
  for (it=myvector.begin(); it<myvector.end(); it++)
    cout << " " << *it;
  cout << endl;

  return 0;
}

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

Complexity

If the new vector size cannot be determined beforehand (which happens in the iterator version for input iterators that are neither forward, bidirectional nor random-access), the complexity is proportional to the number of elements inserted times the distance between position and the end of the vector.

See also