class template
<iterator>

std::front_insert_iterator

template <class Container> class front_insert_iterator;
Front insert iterator

Front-insert iterators are special output iterators designed to allow algorithms that usually overwrite elements (such as copy) to instead insert new elements at the beginning of the container.

The container needs to have a push_front member function (such as the standard containers deque and list).

Using the assignment operator on the front_insert_iterator (both while being dereferenced or not), causes the container to expand by one element, which is initialized to the value assigned.

The other typical operators of an output iterator are also defined for front_insert_iterator but have no effect: all values assigned are inserted at the beginning of the container.

It is defined with the same behavior as:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
 
template <class Container>
  class front_insert_iterator :
    public iterator<output_iterator_tag,void,void,void,void>
{
protected:
  Container* container;

public:
  typedef Container container_type;
  explicit front_insert_iterator (Container& x) : container(&x) {}
  front_insert_iterator<Container>& operator= (typename Container::const_reference value)
    { container->push_front(value); return *this; }
  front_insert_iterator<Container>& operator* ()
    { return *this; }
  front_insert_iterator<Container>& operator++ ()
    { return *this; }
  front_insert_iterator<Container> operator++ (int)
    { return *this; }
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
 
template <class Container>
  class front_insert_iterator :
    public iterator<output_iterator_tag,void,void,void,void>
{
protected:
  Container* container;

public:
  typedef Container container_type;
  explicit front_insert_iterator (Container& x) : container(&x) {}
  front_insert_iterator<Container>& operator= (const typename Container::value_type& value)
    { container->push_front(value); return *this; }
  front_insert_iterator<Container>& operator= (typename Container::value_type&& value)
    { container->push_front(std::move(value)); return *this; }
  front_insert_iterator<Container>& operator* ()
    { return *this; }
  front_insert_iterator<Container>& operator++ ()
    { return *this; }
  front_insert_iterator<Container> operator++ (int)
    { return *this; }
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
 
template <class Container>
  class front_insert_iterator :
    public iterator<output_iterator_tag,void,void,void,void>
{
protected:
  Container* container;

public:
  typedef Container container_type;
  explicit front_insert_iterator (Container& x) : container(std::addressof(x)) {}
  front_insert_iterator<Container>& operator= (const typename Container::value_type& value)
    { container->push_front(value); return *this; }
  front_insert_iterator<Container>& operator= (typename Container::value_type&& value)
    { container->push_front(std::move(value)); return *this; }
  front_insert_iterator<Container>& operator* ()
    { return *this; }
  front_insert_iterator<Container>& operator++ ()
    { return *this; }
  front_insert_iterator<Container> operator++ (int)
    { return *this; }
};


The library provides a function, called front_inserter, that automatically generates a front_insert_iterator class from a suitable container.

Template parameters

Container
A container class with member push_front defined (such as the standard containers deque and list).

Member types

memberdefinition in front_insert_iterator
iterator_categoryoutput_iterator_tag
value_typevoid
difference_typevoid
pointervoid
referencevoid
iterator_typevoid

Member functions

constructor
front_insert_iterator objects are constructed from a container, of which they keep a reference internally.
operator=
Inserts a new element at the beginning of the container, initializing it with the argument.
operator*
Does nothing. Returns a reference to the object.
operator++
Does nothing. Returns a reference to the object.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
 
// front_insert_iterator example
#include <iostream>     // std::cout
#include <iterator>     // std::front_insert_iterator
#include <deque>        // std::deque
#include <algorithm>    // std::copy

int main () {
  std::deque<int> foo, bar;
  for (int i=1; i<=5; i++)
  { foo.push_back(i); bar.push_back(i*10); }

  std::front_insert_iterator< std::deque<int> > front_it (foo);

  std::copy (bar.begin(),bar.end(),front_it);

  std::cout << "foo:";
  for ( std::deque<int>::iterator it = foo.begin(); it!= foo.end(); ++it )
	  std::cout << ' ' << *it;
  std::cout << '\n';

  return 0;
}


Output:

50 40 30 20 10 1 2 3 4 5

See also

front_inserter
Constructs front insert iterator (function template )
back_insert_iterator
Back insert iterator (class template )
insert_iterator
Insert iterator (class template )

C++