## back_insert_iterator, back_inserter

    Insert Iterator

- Summary
- Data Type and Member Function Indexes
- Synopsis
- Description
- Interface
- Types
- Constructors
- Operators
- Helper Functions
- Example
- Warnings
- See Also

### Summary

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

### Data Type and Member Function Indexes
(exclusive of constructors and destructors)

Data Types
container_type

Member Functions
back_inserter() operator*() operator++() operator=()

### Synopsis

    #include <iterator>
    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 back_insert_iterator is used to insert items at the end of a collection. The function `back_inserter` creates an instance of a back_insert_iterator for a particular collection type. A back_insert_iterator can be used with vectors, deques, and lists, but not with maps or sets.

### Interface

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

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

### Types

    container_type

The type of container acted on by this iterator.

### Constructors

    explicit
    back_insert_iterator (Container& x);

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

### Operators

    back_insert_iterator<Container>&
    operator= (const typename Container::value_type& value);

Inserts a copy of `value` on the end of the container, and returns `*this`.

    back_insert_iterator<Container>&
    operator* ();

Returns `*this`.

    back_insert_iterator<Container>&
    operator++ ();
    back_insert_iterator<Container>
    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`. This function allows you to create insert iterators inline.

### Example

    //
    // ins_itr.cpp
    //
     #include <iterator>
     #include <deque>
     #include <iostream>
     using namespace std;

     int main ()
     {
       //
       // Initialize a deque using an array.
       //
       int arr[4] = { 3,4,7,8 };
       deque<int> d(arr+0, arr+4);
       //
       // Output the original deque.
       //
       cout << "Start with a deque: " << endl << "     ";
       copy(d.begin(), d.end(),
            ostream_iterator<int,char>(cout," "));
       //
       // Insert into the middle.
       //
       insert_iterator<deque<int> > ins(d, d.begin()+2);
       *ins = 5; *ins = 6;
       //
       // Output the new deque.
       //
       cout << endl << endl;
       cout << "Use an insert_iterator: " << endl << "     ";
       copy(d.begin(), d.end(),
            ostream_iterator<int,char>(cout," "));
       //
       // A deque of four 1s.
       //
       deque<int> d2(4, 1);
       //
       // Insert d2 at front of d.
       //
       copy(d2.begin(), d2.end(), front_inserter(d));
       //
       // Output the new deque.
       //
       cout << endl << endl;
       cout << "Use a front_inserter: " << endl << "     ";
       copy(d.begin(), d.end(),
            ostream_iterator<int,char>(cout," "));
       //
       // Insert d2 at back of d.
       //
       copy(d2.begin(), d2.end(), back_inserter(d));
       //
       // Output the new deque.
       //
       cout << endl << endl;
       cout << "Use a back_inserter: " << endl << "     ";
       copy(d.begin(), d.end(),
            ostream_iterator<int,char>(cout," "));
       cout << 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

### Warnings

If your compiler does not support default template parameters, then you always need to supply the `Allocator` template argument. For instance, you have to write:

`vector<int,allocator<int> >`

instead of:

`vector<int>`

If your compiler does not support namespaces, then you do not need the using declaration for `std`.

### See Also

Insert Iterators

Copyright (c) 1998, Rogue Wave Software, Inc.
Send mail to report errors or comment on the documentation.
OEM Release, June 1998