list::insert

Inserts an element or a number of elements or a range of elements into a list at a specified position.

iterator insert(
   const_iterator _Where,
   const Type& _Val
);
iterator insert(
   const_iterator _Where,
   Type&& _Val
);
void insert(
   iterator _Where,
   size_type _Count,
   const Type& _Val
);
template<class InputIterator>
   void insert(
      iterator _Where,
      InputIterator _First,
      InputIterator _Last
   );

Parameters

Parameter

Description

_Where

The position in the target list where the first element is inserted.

_Val

The value of the element being inserted into the list.

_Count

The number of elements being inserted into the list.

_First

The position of the first element in the range of elements in the argument list to be copied.

_Last

The position of the first element beyond the range of elements in the argument list to be copied.

Return Value

The first two insert functions return an iterator that points to the position where the new element was inserted into the list.

Example

// list_class_insert.cpp
// compile with: /EHsc
#include <list>
#include <iostream>
#include <string>

int main( ) 
{
   using namespace std;
   list <int> c1, c2;
   list <int>::iterator Iter;
   
   c1.push_back( 10 );
   c1.push_back( 20 );
   c1.push_back( 30 );
   c2.push_back( 40 );
   c2.push_back( 50 );
   c2.push_back( 60 );

   cout << "c1 =";
   for ( Iter = c1.begin( ); Iter != c1.end( ); Iter++ )
      cout << " " << *Iter;
   cout << endl;

   Iter = c1.begin( );
   Iter++;
   c1.insert( Iter, 100 );
   cout << "c1 =";
   for ( Iter = c1.begin( ); Iter != c1.end( ); Iter++ )
      cout << " " << *Iter;
   cout << endl;

   Iter = c1.begin( );
   Iter++;
   Iter++;
   c1.insert( Iter, 2, 200 );

   cout << "c1 =";
   for ( Iter = c1.begin( ); Iter != c1.end( ); Iter++ )
      cout << " " << *Iter;
   cout << endl;

   c1.insert( ++c1.begin( ), c2.begin( ),--c2.end( ) );

   cout << "c1 =";
   for ( Iter = c1.begin( ); Iter != c1.end( ); Iter++ )
      cout << " " << *Iter;
   cout << endl;

// initialize a list of strings by moving
   list < string > c2;
   string str("a");

   c2.insert( c2.begin(), move( str ) );
   cout << "Moved first element: " << c2.front( ) << endl;
}

Output

c1 = 10 20 30
c1 = 10 100 20 30
c1 = 10 100 200 200 20 30
c1 = 10 40 50 100 200 200 20 30
Moved first element: a

Requirements

Header: <list>

Namespace: std

See Also

Reference

list Class

list::insert (STL Samples)

Standard Template Library

Other Resources

list Class Members