Share via


front_insert_iterator Class

 

The latest version of this topic can be found at front_insert_iterator Class.

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

Syntax

template <class Container>  
class front_insert_iterator;  

Parameters

Container
The type of container into the front of which elements are to be inserted by a front_insert_iterator.

Remarks

The container must satisfy the requirements for a front insertion sequence where is it possible to insert elements at the beginning of the sequence in amortized constant time. The Standard Template Library sequence containers defined by the deque Class and list Class provide the needed push_front member function and satisfy these requirements. By contrast, sequence containers defined by the vector Class do not satisfy these requirements and cannot be adapted to use with front_insert_iterators. A front_insert_iterator must always be initialized with its container.

Constructors

front_insert_iterator Creates an iterator that can insert elements at the front of a specified container object.

Typedefs

container_type A type that represents the container into which a front insertion is to be made.
reference A 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 front insertion.
operator++ Increments the front_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 front insertion.

Requirements

Header: <iterator>

Namespace: std

front_insert_iterator::container_type

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

typedef Container container_type;  

Remarks

The type is a synonym for the template parameter Container.

Example

// front_insert_iterator_container_type.cpp  
// compile with: /EHsc  
#include <iterator>  
#include <list>  
#include <iostream>  
  
int main( )  
{  
   using namespace std;  
  
   list<int> L1;  
   front_insert_iterator<list<int> >::container_type L2 = L1;  
   front_inserter ( L2 ) = 20;  
   front_inserter ( L2 ) = 10;  
   front_inserter ( L2 ) = 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 10 20 ).  
*\  

front_insert_iterator::front_insert_iterator

Creates an iterator that can insert elements at the front of a specified container object.

explicit front_insert_iterator(Container& _Cont);

Parameters

_Cont
The container object into which the front_insert_iterator is to insert elements.

Return Value

A front_insert_iterator for the parameter container object.

Example

// front_insert_iterator_front_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 < 9 ; ++i )    
   {  
      L.push_back ( 2 * 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  
   front_inserter ( L ) = 20;  
  
   // Alternatively, one may use the template function  
   front_insert_iterator< list < int> > Iter(L);  
 *Iter = 30;  
  
   cout << "After the front 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:  
 ( -2 0 2 4 6 8 10 12 14 16 ).  
After the front insertions, the list L is:  
 ( 30 20 -2 0 2 4 6 8 10 12 14 16 ).  
*\  

front_insert_iterator::operator*

Dereferences the insert iterator returning the element it addresses.

front_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

// front_insert_iterator_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 = -1 ; i < 9 ; ++i )   
   {  
      L.push_back ( 2 * i );  
   }  
  
   cout << "The list L is:\n ( ";  
   for ( L_Iter = L.begin( ) ; L_Iter != L.end( ); L_Iter++)  
      cout << *L_Iter << " ";  
   cout << ")." << endl;  
  
   front_insert_iterator< list < int> > Iter(L);  
 *Iter = 20;  
  
   // Alternatively, you may use  
   front_inserter ( L ) = 30;  
  
   cout << "After the front 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:  
 ( -2 0 2 4 6 8 10 12 14 16 ).  
After the front insertions, the list L is:  
 ( 30 20 -2 0 2 4 6 8 10 12 14 16 ).  
*\  

front_insert_iterator::operator++

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

front_insert_iterator<Container>& operator++();

front_insert_iterator<Container> operator++(int);

Return Value

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

Remarks

Both preincrementation and postincrementation operators return the same result.

Example

// front_insert_iterator_op_incre.cpp  
// compile with: /EHsc  
#include <iterator>  
#include <list>  
#include <iostream>  
  
int main( )  
{  
   using namespace std;  
  
   list<int> L1;  
   front_insert_iterator<list<int> > iter ( L1 );  
 *iter = 10;  
   iter++;  
 *iter = 20;  
   iter++;  
 *iter = 30;  
   iter++;  
  
   list <int>::iterator vIter;  
   cout << "The list L1 is: ( ";  
   for ( vIter = L1.begin ( ) ; vIter != L1.end ( ); vIter++ )  
      cout << *vIter << " ";  
   cout << ")." << endl;  
}  
\* Output:   
The list L1 is: ( 30 20 10 ).  
*\  

front_insert_iterator::operator=

Appends (pushes) a value onto the front of the container.

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

front_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 last element inserted at the front of the container.

Remarks

The first member operator evaluates container.push_front( val), then returns *this.

The second member operator evaluates

container->push_front((typename Container::value_type&&) val),

then returns *this.

Example

// front_insert_iterator_op_assign.cpp  
// compile with: /EHsc  
#include <iterator>  
#include <list>  
#include <iostream>  
  
int main( )  
{  
   using namespace std;  
  
   list<int> L1;  
   front_insert_iterator<list<int> > iter ( L1 );  
 *iter = 10;  
   iter++;  
 *iter = 20;  
   iter++;  
 *iter = 30;  
   iter++;  
  
   list <int>::iterator vIter;  
   cout << "The list L1 is: ( ";  
   for ( vIter = L1.begin ( ) ; vIter != L1.end ( ); vIter++ )  
      cout << *vIter << " ";  
   cout << ")." << endl;  
}  
\* Output:   
The list L1 is: ( 30 20 10 ).  
*\  

front_insert_iterator::reference

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

typedef typename Container::reference reference;  

Example

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

See Also

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