## insert_iterator, inserter

    Insert Iterator

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

### Summary

An insert iterator used to insert items into a collection rather than overwrite the collection.

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

Data Types
container_type

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

### Synopsis

    #include <iterator>
    template <class Container>
    class 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 insert_iterator is used to insert items into a specified location of a collection. The function `inserter` creates an instance of an insert_iterator given a particular collection type and iterator. An insert_iterator can be used with vectors, deques, lists, maps and sets.

### Interface

    template <class Container>
    class insert_iterator : public
          iterator<output_iterator_tag,void,void,void,void> ;  {
    protected:
       Container* container;
    public:
       typedef Container container_type;
       insert_iterator (Container&, typename Container::iterator);
       insert_iterator<Container>&
        operator= (const typename Container::value_type&);
       insert_iterator<Container>& operator* ();
       insert_iterator<Container>& operator++ ();
       insert_iterator<Container>& operator++ (int);
    };

    template <class Container, class Iterator>
    insert_iterator<Container> inserter (Container&, Iterator)

### Types

    container_type

The type of container acted on by the iterator.

### Constructors

    insert_iterator(Container& x,
                      typename Container::iterator i);

Creates an instance of an insert_iterator associated with container `x` and iterator `i.`

### Operators

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

Inserts a copy of `value` into the container at the location specified by the `insert_iterator`, increments the iterator, and returns `*this`.

    insert_iterator<Container>&
    operator*();

Returns `*this` (the input iterator itself).

    insert_iterator<Container>&
    operator++();
    insert_iterator<Container>&
    operator++(int);

Increments the insert iterator and returns `*this`.

### Non-member Functions

    template <class Container, class Iterator>
    insert_iterator<Container>
    inserter(Container& x, Iterator i);

Returns an insert_iterator that inserts elements into container `x` at location `i`. This function allows you to create insert iterators inline.

### Example

     #include <iterator>
     #include <vector>
     #include <iostream>
     using namespace std;
     int main()
     {
       //Initialize a vector using an array
       int arr[4] = {3,4,7,8};
       vector<int> v(arr,arr+4);
       //Output the original vector
       cout << "Start with a vector: " << endl << "     ";
       copy(v.begin(),v.end(),
            ostream_iterator<int,char>(cout," "));
       //Insert into the middle
       insert_iterator<vector<int> >  ins(v, v.begin()+2);
       *ins = 5;
       *ins = 6;
       //Output the new vector
       cout << endl << endl;
       cout << "Use an insert_iterator: " << endl << "     ";
       copy(v.begin(),v.end(),
            ostream_iterator<int,char>(cout," "));
       return 0;
     }

### 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

back_insert_iterator, front_insert_iterator, Insert Iterators

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