C++ Standard Library C++ STL Library

C++ <list> - insert() Function



The C++ list::insert function is used to insert new elements before the element at the specified position. This results into increasing the list size by the number of elements inserted.

Syntax

//single element version  
iterator insert (iterator position, const value_type& val);

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

//range version 
template <class InputIterator>
  void insert (iterator position, InputIterator first, InputIterator last);
//single element version 
iterator insert (const_iterator position, const value_type& val);

//fill version  
iterator insert (const_iterator position, size_type n, const value_type& val);

//range version 
template <class InputIterator>
  iterator insert (const_iterator position, InputIterator first, InputIterator last);

//move version  
iterator insert (const_iterator position, value_type&& val);

//initializer list version 
iterator insert (const_iterator position, initializer_list<value_type> ilist);

Parameters

position Specify the iterator position in the list where the new elements need to be inserted.
val Specify the value to be inserted.
n Specify the number of new elements to be inserted.
first Specify the starting position of InputIterator. Copies of the elements in the range [first,last) are inserted at position (in the same order).
last Specify the last position of InputIterator. Copies of the elements in the range [first,last) are inserted at position (in the same order).
ilist Specify the initializer_list object.

Return Value

Returns an iterator which points to the first element of the newly inserted elements.

Time Complexity

Linear i.e, Θ(n)

Example:

In the example below, the list::insert function is used to insert elements in the given list.

#include <iostream>
#include <list>
using namespace std;
 
int main (){
  list<int> list1 = {10, 20, 30};
  list<int> list2 = {10, 20, 30};
  list<int> list3 = {10, 20, 30};
  list<int> list4 = {100, 200, 300};

  list<int>::iterator it;

  //single element version 
  it = list1.begin();  it++;   //points to second element
  list1.insert(it, 55);

  //fill version - fill 3 new elements at specified location 
  it = list2.begin(); 
  list2.insert(++it, 3, 55);

  //range version 
  it = list3.begin();
  list3.insert(++it, list4.begin(), list4.end());

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

  cout<<"\nlist2 contains: ";
  for(it = list2.begin(); it != list2.end(); ++it)
    cout<<*it<<" ";

  cout<<"\nlist3 contains: ";
  for(it = list3.begin(); it != list3.end(); ++it)
    cout<<*it<<" ";

  return 0;
}

The output of the above code will be:

list1 contains: 10 55 20 30 
list2 contains: 10 55 55 55 20 30 
list3 contains: 10 100 200 300 20 30 

Example:

The move version of the insert function can also be used to insert the content of one list into the another list. Consider the example below.

#include <iostream>
#include <list>
using namespace std;
 
int main (){
  list<int> list1 = {10, 20, 30};
  list<int> list2 = {100, 200, 300};
  list<int>::iterator it;

  //move version - moving content of list1 to list2 
  for(it = list1.begin(); it != list1.end(); ++it)
    list2.insert(list2.end(), move(*it));

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

  cout<<"\nlist2 contains: ";
  for(it = list2.begin(); it != list2.end(); ++it)
    cout<<*it<<" ";

  return 0;
}

The output of the above code will be:

list1 contains: 10 20 30 
list2 contains: 100 200 300 10 20 30 

Example:

Similarly, the initializer list version can be used to insert elements in the given list.

#include <iostream>
#include <list>
using namespace std;
 
int main (){
  list<int> MyList = {10, 20, 30};
  list<int>::iterator it;

  //initializer list version 
  initializer_list<int> ilist = {11, 22, 33, 44, 55};
  it = MyList.begin();
  MyList.insert(++it, ilist); 

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

  return 0;
}

The output of the above code will be:

MyList contains: 10 11 22 33 44 55 20 30 

❮ C++ <list> Library

5