class template
<iterator>

std::insert_iterator

template <class Container> class insert_iterator;
Insert iterator

Insert iterators are special output iterators designed to allow algorithms that usually overwrite elements (such as copy) to instead insert new elements at a specific position in the container.

The container needs to have an insert member function (such as most standard containers).

Using the assignment operator on the 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 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
20
21
 
template <class Container>
  class insert_iterator :
    public iterator<output_iterator_tag,void,void,void,void>
{
protected:
  Container* container;
  typename Container::iterator iter;

public:
  typedef Container container_type;
  explicit insert_iterator (Container& x, typename Container::iterator i)
    : container(&x), iter(i) {}
  insert_iterator<Container>& operator= (typename Container::const_reference value)
    { iter=container->insert(iter,value); ++iter; return *this; }
  insert_iterator<Container>& operator* ()
    { return *this; }
  insert_iterator<Container>& operator++ ()
    { return *this; }
  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
22
23
 
template <class Container>
  class insert_iterator :
    public iterator<output_iterator_tag,void,void,void,void>
{
protected:
  Container* container;
  typename Container::iterator iter;

public:
  typedef Container container_type;
  explicit insert_iterator (Container& x, typename Container::iterator i)
    : container(&x), iter(i) {}
  insert_iterator<Container>& operator= (const typename Container::value_type& value)
    { iter=container->insert(iter,value); ++iter; return *this; }
  insert_iterator<Container>& operator= (typename Container::value_type&& value)
    { iter=container->insert(iter,std::move(value)); ++iter; return *this; }
  insert_iterator<Container>& operator* ()
    { return *this; }
  insert_iterator<Container>& operator++ ()
    { return *this; }
  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
22
23
 
template <class Container>
  class insert_iterator :
    public iterator<output_iterator_tag,void,void,void,void>
{
protected:
  Container* container;
  typename Container::iterator iter;

public:
  typedef Container container_type;
  explicit insert_iterator (Container& x, typename Container::iterator i)
    : container(std::addressof(x)), iter(i) {}
  insert_iterator<Container>& operator= (const typename Container::value_type& value)
    { iter=container->insert(iter,value); ++iter; return *this; }
  insert_iterator<Container>& operator= (typename Container::value_type&& value)
    { iter=container->insert(iter,std::move(value)); ++iter; return *this; }
  insert_iterator<Container>& operator* ()
    { return *this; }
  insert_iterator<Container>& operator++ ()
    { return *this; }
  insert_iterator<Container> operator++ (int)
    { return *this; }
};


The library provides a function, called inserter, that automatically generates an insert_iterator class from a container and an iterator.

Template parameters

Container
A container class with member insert defined.

Member types

memberdefinition in 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) and an iterator (of which they keep a copy).
operator=
Inserts a new element in the container at the position pointed by the iterator passed on construction, initializing the new element 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
23
24
25
 
// insert_iterator example
#include <iostream>     // std::cout
#include <iterator>     // std::insert_iterator
#include <list>         // std::list
#include <algorithm>    // std::copy

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

  std::list<int>::iterator it = foo.begin();
  advance(it,3);

  std::insert_iterator< std::list<int> > insert_it (foo,it);

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

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

  return 0;
}


Output:

1 2 3 10 20 30 40 50 4 5

See also

inserter
Construct insert iterator (function template )
back_insert_iterator
Back insert iterator (class template )
front_insert_iterator
Front insert iterator (class template )

C++