class template
<iterator>

std::back_insert_iterator

template <class Container> class back_insert_iterator;
Back insert iterator

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

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

Using the assignment operator on the back_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 back_insert_iterator but have no effect: all values assigned are inserted at the end 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 back_insert_iterator :
    public iterator<output_iterator_tag,void,void,void,void>
{
protected:
  Container* container;

public:
  typedef Container container_type;
  explicit back_insert_iterator (Container& x) : container(&x) {}
  back_insert_iterator<Container>& operator= (typename Container::const_reference value)
    { container->push_back(value); return *this; }
  back_insert_iterator<Container>& operator* ()
    { return *this; }
  back_insert_iterator<Container>& operator++ ()
    { return *this; }
  back_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 back_insert_iterator :
    public iterator<output_iterator_tag,void,void,void,void>
{
protected:
  Container* container;

public:
  typedef Container container_type;
  explicit back_insert_iterator (Container& x) : container(&x) {}
  back_insert_iterator<Container>& operator= (const typename Container::value_type& value)
    { container->push_back(value); return *this; }
  back_insert_iterator<Container>& operator= (typename Container::value_type&& value)
    { container->push_back(std::move(value)); return *this; }
  back_insert_iterator<Container>& operator* ()
    { return *this; }
  back_insert_iterator<Container>& operator++ ()
    { return *this; }
  back_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 back_insert_iterator :
    public iterator<output_iterator_tag,void,void,void,void>
{
protected:
  Container* container;

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


The library provides a function, called back_inserter, that automatically generates a back_insert_iterator class from a suitable container.

Template parameters

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

Member types

memberdefinition in back_insert_iterator
iterator_categoryoutput_iterator_tag
value_typevoid
difference_typevoid
pointervoid
referencevoid
iterator_typevoid

Member functions

constructor
back_insert_iterator objects are constructed from a container, of which they keep a reference internally.
operator=
Inserts a new element at the end 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
 
// back_insert_iterator example
#include <iostream>     // std::cout
#include <iterator>     // std::back_insert_iterator
#include <vector>       // std::vector
#include <algorithm>    // std::copy

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

  std::back_insert_iterator< std::vector<int> > back_it (foo);

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

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

  return 0;
}


Output:

foo: 1 2 3 4 5 10 20 30 40 50

See also

back_inserter
Construct back insert iterator (function template )
front_insert_iterator
Front insert iterator (class template )
insert_iterator
Insert iterator (class template )

C++