list::splice

Removes elements from the argument list and inserts them into the target list.

void splice(
   iterator _Where,
   list<Type, Allocator>& _Right
);
void splice(
   iterator _Where,
   list<Type, Allocator>& _Right,
   iterator _First
);
void splice(
   iterator _Where,
   list<Type, Allocator>& _Right,
   iterator _First,
   iterator _Last
);

Parameters

  • _Where
    The position in the target list before which the elements of the argument list are to be inserted.

  • _Right
    The argument list that is to be inserted into the target list.

  • _First
    The first element in the range to be inserted from the argument list.

  • _Last
    The first element beyond the range to be inserted from the argument list.

Remarks

The first member function inserts all elements in the argument list before the element located at _Where in the target list. It also removes all elements from the argument list.

The second member function removes the element pointed to by _First in the argument list and inserts it before the element in the target list pointed to by _Where.

The third member function inserts the range designated by [_First, _Last) from the argument list before the element in the target list pointed to by _Where. It also removes the range inserted from the argument list.

In all cases, only iterators or references that point at spliced elements become invalid.

Example

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

int main( )
{
   using namespace std;
   list <int> c1, c2, c3, c4;
   list <int>::iterator c1_Iter, c2_Iter, w_Iter, f_Iter, l_Iter;
   
   c1.push_back( 10 );
   c1.push_back( 11 );
   c2.push_back( 12 );
   c2.push_back( 20 );
   c2.push_back( 21 );
   c3.push_back( 30 );
   c3.push_back( 31 );
   c4.push_back( 40 );
   c4.push_back( 41 );
   c4.push_back( 42 );

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

   cout << "c2 =";
   for ( c2_Iter = c2.begin( ); c2_Iter != c2.end( ); c2_Iter++ )
      cout << " " << *c2_Iter;
   cout << endl;

   w_Iter = c2.begin( );
   w_Iter++;
   c2.splice( w_Iter,c1 );
   cout << "After splicing c1 into c2: c2 =";
   for ( c2_Iter = c2.begin( ); c2_Iter != c2.end( ); c2_Iter++ )
      cout << " " << *c2_Iter;
   cout << endl;

   f_Iter = c3.begin( );
   c2.splice( w_Iter,c3, f_Iter );
   cout << "After splicing the first element of c3 into c2: c2 =";
   for ( c2_Iter = c2.begin( ); c2_Iter != c2.end( ); c2_Iter++ )
      cout << " " << *c2_Iter;
   cout << endl;

   f_Iter = c4.begin( );
   l_Iter = c4.end( );
   l_Iter--;
   c2.splice( w_Iter,c4, f_Iter, l_Iter );
   cout << "After splicing a range of c4 into c2: c2 =";
   for ( c2_Iter = c2.begin( ); c2_Iter != c2.end( ); c2_Iter++ )
      cout << " " << *c2_Iter;
   cout << endl;
}
c1 = 10 11
c2 = 12 20 21
After splicing c1 into c2: c2 = 12 10 11 20 21
After splicing the first element of c3 into c2: c2 = 12 10 11 30 20 21
After splicing a range of c4 into c2: c2 = 12 10 11 30 40 41 20 21

Requirements

Header: <list>

Namespace: std

See Also

Reference

list Class

Standard Template Library

Other Resources

list Class Members