insert_iterator Class

 

For the latest documentation on Visual Studio 2017, see Visual Studio 2017 Documentation.

Describes an iterator adaptor that satisfies the requirements of an output iterator. It inserts, rather than overwrites, elements into a sequence and thus provides semantics that are different from the overwrite semantics provided by the iterators of the C++ sequence and associative containers. The insert_iterator class is templatized on the type of container being adapted.

template <class Container>  
class insert_iterator;

Parameters

Container
The type of container into which elements are to be inserted by an insert_iterator.

The container of type Container must satisfy the requirements for a variable-sized container and have a two-argument insert member function where the parameters are of type Container::iterator and Container::value_type and that returns a type Container::iterator. Standard Template Library sequence and sorted associative containers satisfy these requirements and can be adapted to use with insert_iterators. For associative containers, the position argument is treated as a hint, which has the potential to improve or degrade performance depending on how good the hint is. An insert_iterator must always be initialized with its container.

Constructors

insert_iteratorConstructs an insert_iterator that inserts an element into a specified position in a container.

Typedefs

container_typeA type that represents the container into which a general insertion is to be made.
referenceA type that provides a reference to an element in a sequence controlled by the associated container.

Operators

operator*Dereferencing operator used to implement the output iterator expression * i = x for a general insertion.
operator++Increments the insert_iterator to the next location into which a value may be stored.
operator=Assignment operator used to implement the output iterator expression * i = x for a general insertion.

Header: <iterator>

Namespace: std

A type that represents the container into which a general insertion is to be made.

typedef Container container_type;

Remarks

The type is a synonym for the template parameter Container.

Example

// insert_iterator_container_type.cpp  
// compile with: /EHsc  
#include <iterator>  
#include <list>  
#include <iostream>  
  
int main( )  
{  
   using namespace std;  
  
   list<int> L1;  
   insert_iterator<list<int> >::container_type L2 = L1;  
   inserter ( L2, L2.end ( ) ) = 20;  
   inserter ( L2, L2.end ( ) ) = 10;  
   inserter ( L2, L2.begin ( ) ) = 40;  
  
   list <int>::iterator vIter;  
   cout << "The list L2 is: ( ";  
   for ( vIter = L2.begin ( ) ; vIter != L2.end ( ); vIter++ )  
      cout << *vIter << " ";  
   cout << ")." << endl;  
}  
\* Output:   
The list L2 is: ( 40 20 10 ).  
*\  

Constructs an insert_iterator that inserts an element into a specified position in a container.

insert_iterator(Container& _Cont, typename Container::iterator _It);

Parameters

_Cont
The container into which the insert_iterator is to insert elements.

_It
The position for the insertion.

Remarks

All containers have the insert member function called by the insert_iterator. For associative containers the position parameter is merely a suggestion. The inserter function provides a convenient way to insert to values.

Example

// insert_iterator_insert_iterator.cpp  
// compile with: /EHsc  
#include <iterator>  
#include <list>  
#include <iostream>  
  
int main( )  
{  
   using namespace std;  
   int i;  
   list <int>::iterator L_Iter;  
  
   list<int> L;  
   for (i = 1 ; i < 4 ; ++i )    
   {  
      L.push_back ( 10 * i );  
   }  
  
   cout << "The list L is:\n ( ";  
   for ( L_Iter = L.begin( ) ; L_Iter != L.end( ); L_Iter++)  
      cout << *L_Iter << " ";  
   cout << ")." << endl;  
  
   // Using the member function to insert an element  
   inserter ( L, L.begin ( ) ) = 2;  
  
   // Alternatively, you may use the template version  
   insert_iterator< list < int> > Iter(L, L.end ( ) );  
 *Iter = 300;  
  
   cout << "After the insertions, the list L is:\n ( ";  
   for ( L_Iter = L.begin( ) ; L_Iter != L.end( ); L_Iter++ )  
      cout << *L_Iter << " ";  
   cout << ")." << endl;  
}  
\* Output:   
The list L is:  
 ( 10 20 30 ).  
After the insertions, the list L is:  
 ( 2 10 20 30 300 ).  
*\  

Dereferences the insert iterator returning the element is addresses.

insert_iterator<Container>& operator*();

Return Value

The member function returns the value of the element addressed.

Remarks

Used to implement the output iterator expression *Iter = value. If Iter is an iterator that addresses an element in a sequence, then *Iter = value replaces that element with value and does not change the total number of elements in the sequence.

Example

// insert_iterator_op_deref.cpp  
// compile with: /EHsc  
#include <iterator>  
#include <list>  
#include <iostream>  
  
int main( )  
{  
   using namespace std;  
   int i;  
   list <int>::iterator L_Iter;  
  
   list<int> L;  
   for (i = 0 ; i < 4 ; ++i )    
   {  
      L.push_back ( 2 * i );  
   }  
  
   cout << "The original list L is:\n ( ";  
   for ( L_Iter = L.begin( ) ; L_Iter != L.end( ); L_Iter++ )  
      cout << *L_Iter << " ";  
   cout << ")." << endl;  
  
   insert_iterator< list < int> > Iter(L, L.begin ( ) );  
 *Iter = 10;  
 *Iter = 20;  
 *Iter = 30;  
  
   cout << "After the insertions, the list L is:\n ( ";  
   for ( L_Iter = L.begin( ) ; L_Iter != L.end( ); L_Iter++ )  
      cout << *L_Iter << " ";  
   cout << ")." << endl;  
}  
\* Output:   
The original list L is:  
 ( 0 2 4 6 ).  
After the insertions, the list L is:  
 ( 10 20 30 0 2 4 6 ).  
*\  

Increments the insert_iterator to the next location into which a value may be stored.

insert_iterator<Container>& operator++();

insert_iterator<Container> operator++(int);

Parameters

A insert_iterator addressing the next location into which a value may be stored.

Remarks

Both preincrementation and postincrementation operators return the same result.

Example

// insert_iterator_op_incr.cpp  
// compile with: /EHsc  
#include <iterator>  
#include <vector>  
#include <iostream>  
  
int main( )  
{  
   using namespace std;  
   int i;  
  
   vector<int> vec;  
   for (i = 1 ; i < 5 ; ++i )   
   {  
      vec.push_back (  i );  
   }  
  
   vector <int>::iterator vIter;  
   cout << "The vector vec is:\n ( ";  
   for ( vIter = vec.begin ( ) ; vIter != vec.end ( ); vIter++ )  
      cout << *vIter << " ";  
   cout << ")." << endl;  
  
   insert_iterator<vector<int> > ii ( vec, vec.begin ( ) );  
 *ii = 30;  
   ii++;  
 *ii = 40;  
   ii++;  
 *ii = 50;  
  
   cout << "After the insertions, the vector vec becomes:\n ( ";  
   for ( vIter = vec.begin ( ) ; vIter != vec.end ( ); vIter++ )  
      cout << *vIter << " ";  
   cout << ")." << endl;  
}  
\* Output:   
The vector vec is:  
 ( 1 2 3 4 ).  
After the insertions, the vector vec becomes:  
 ( 30 40 50 1 2 3 4 ).  
*\  

Inserts a value into the container and returns the iterator updated to point to the new element.

insert_iterator<Container>& operator=(
    typename Container::const_reference val,);

insert_iterator<Container>& operator=(
    typename Container::value_type&& val);

Parameters

val
The value to be assigned to the container.

Return Value

A reference to the element inserted into the container.

Remarks

The first member operator evaluates

Iter = container->insert(Iter, val);

++Iter;

then returns *this.

The second member operator evaluates

Iter = container->insert(Iter, std::move(val));

++Iter;

then returns *this.

Example

// insert_iterator_op_assign.cpp  
// compile with: /EHsc  
#include <iterator>  
#include <list>  
#include <iostream>  
  
int main( )  
{  
   using namespace std;  
   int i;  
   list <int>::iterator L_Iter;  
  
   list<int> L;  
   for (i = 0 ; i < 4 ; ++i )   
   {  
      L.push_back ( 2 * i );  
   }  
  
   cout << "The original list L is:\n ( ";  
   for ( L_Iter = L.begin( ) ; L_Iter != L.end( ); L_Iter++ )  
      cout << *L_Iter << " ";  
   cout << ")." << endl;  
  
   insert_iterator< list < int> > Iter(L, L.begin ( ) );  
 *Iter = 10;  
 *Iter = 20;  
 *Iter = 30;  
  
   cout << "After the insertions, the list L is:\n ( ";  
   for ( L_Iter = L.begin( ) ; L_Iter != L.end( ); L_Iter++ )  
      cout << *L_Iter << " ";  
   cout << ")." << endl;  
}  
\* Output:   
The original list L is:  
 ( 0 2 4 6 ).  
After the insertions, the list L is:  
 ( 10 20 30 0 2 4 6 ).  
*\  

A type that provides a reference to an element in a sequence controlled by the associated container.

typedef typename Container::reference reference;

Remarks

The type describes a reference to an element of the sequence controlled by the associated container.

Example

// insert_iterator_container_reference.cpp  
// compile with: /EHsc  
#include <iterator>  
#include <list>  
#include <iostream>  
  
int main( )  
{  
   using namespace std;  
  
   list<int> L;  
   insert_iterator<list<int> > iivIter( L , L.begin ( ) );  
 *iivIter = 10;  
 *iivIter = 20;  
 *iivIter = 30;  
  
   list<int>::iterator LIter;  
   cout << "The list L is: ( ";  
   for ( LIter = L.begin ( ) ; LIter != L.end ( ); LIter++ )  
      cout << *LIter << " ";  
   cout << ")." << endl;  
  
   insert_iterator<list<int> >::reference   
        RefFirst = *(L.begin ( ));  
   cout << "The first element in the list L is: "   
        << RefFirst << "." << endl;  
}  
\* Output:   
The list L is: ( 10 20 30 ).  
The first element in the list L is: 10.  
*\  

<iterator>
Thread Safety in the C++ Standard Library
Standard Template Library

Show: