Apache C++ Standard Library Reference Guide

## back_insert_iterator, back_inserter()

Library: Iterators

    back_insert_iterator  iterator

- Local Index
- Summary
- Synopsis
- Description
- Interface
- Member Types
- Constructors
- Operators
- Helper Functions
- Example
- See Also
- Standards Conformance

### Local Index

#### Members

back_inserter() back_insert_iterator() | container_type operator*() | operator++() operator=() |

### Summary

An output iterator used to insert items at the end of a collection

### Synopsis

    #include <iterator>

    namespace std {
      template <class Container>
      class back_insert_iterator;
    }

### Description

Insert iterators let you insert new elements into a collection rather than copy a new element's value over the value of an existing element. The class template specialization back_insert_iterator is used to insert items at the end of a collection. The convenience function template `back_inserter()` creates an instance of a back_insert_iterator for a particular collection type. A back_insert_iterator can be used with any container that defines the `push_back()` member function, specifically all sequences (e.g., vector, deque, basic_string, and list), but not with associative containers (e.g., map or set).

### Interface

    namespace std {

      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_type&);
         back_insert_iterator& operator=
              (const typename
               container_type::const_reference value);
         back_insert_iterator& operator* ();
         back_insert_iterator& operator++ ();
         back_insert_iterator operator++ (int);
      };

      template <class Container>
        back_insert_iterator<Container> back_inserter(Container&);
    }

### Member Types

    container_type

The type of container acted on by this iterator.

### Constructors

    explicit
    back_insert_iterator (container_type& x);

Constructor. Creates an instance of a back_insert_iterator associated with container `x.`

### Operators

    back_insert_iterator&
    operator= (const typename container_type::constant_reference value);

Inserts a copy of `value` at the end of the container by calling `container->push_back(value)`, and returns `*this`.

    back_insert_iterator&
    operator* ();

Returns `*this` (the iterator itself).

    back_insert_iterator&
    operator* ();

Returns `*this`.

    back_insert_iterator&
    operator++ ();
    back_insert_iterator
    operator++ (int);

Increments the input iterator and returns `*this`.

### Helper Functions

    template <class Container>
    back_insert_iterator<Container>
    back_inserter (Container& x)

Returns a back_insert_iterator that inserts elements at the end of container `x`.

### Example

    //
    //  ins_itr.cpp
    //

    #include <algorithm>   // for copy
    #include <iostream>    // for cout, endl
    #include <iterator>    // for ostream_iterator, xxx_inserter
    #include <deque>       // for deque

    int main ()
    {
        // Typedefs for convenience.
        typedef std::deque<int, std::allocator<int> >   Deque;
        typedef std::ostream_iterator<int, char,
                               std::char_traits<char> > os_iter;

        // Initialize a deque using an array.
        Deque::value_type arr[] = { 3, 4, 7, 8 };
        Deque d (arr, arr + sizeof arr / sizeof *arr);

        // Output the original deque.
        std::cout << "Start with a deque: \n     ";
        std::copy (d.begin (), d.end (), os_iter (std::cout, " "));

        // Insert into the middle.
        std::insert_iterator<Deque> ins (d, d.begin () + 2);
        *ins = 5;
        *ins = 6;

        // Output the new deque.
        std::cout << "\n\nUse an insert_iterator: \n     ";
        std::copy (d.begin (), d.end (), os_iter (std::cout, " "));

        // A deque of four 1s.
        Deque d2 (4, 1);

        // Insert d2 at front of d.
        std::copy (d2.begin (), d2.end (),
                   std::front_inserter (d));

        // Output the new deque.
        std::cout << "\n\nUse a front_inserter: \n     ";
        std::copy (d.begin (), d.end (), os_iter (std::cout, " "));

        // Insert d2 at back of d.
        std::copy (d2.begin (), d2.end (), std::back_inserter (d));

        // Output the new deque.
        std::cout << "\n\nUse a back_inserter: \n     ";
        std::copy (d.begin (), d.end (), os_iter (std::cout, " "));

        std::cout << std::endl;

        return 0;
    }

    Program Output

    Start with a deque:
         3 4 7 8

    Use an insert_iterator:
         3 4 5 6 7 8

    Use a front_inserter:
         1 1 1 1 3 4 5 6 7 8

    Use a back_inserter:
         1 1 1 1 3 4 5 6 7 8 1 1 1 1

### See Also

Insert Iterators

### Standards Conformance

ISO/IEC 14882:1998 -- International Standard for Information Systems -- Programming Language C++, Section 24.4.2.1