Apache C++ Standard Library Reference Guide

## insert_iterator, inserter()

Library: Iterators

    insert_iterator  iterator

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

### Local Index

#### Members

container_type insert_iterator() | operator*() operator++() | operator=()

#### Non-Members

inserter() |

### Summary

insert_iterator is an insert iterator used to insert items into a collection rather than overwrite the collection

### Synopsis

    #include <iterator>

    namespace std {
      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

    namespace std{

      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)
    }

### Member 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`.

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

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

back_insert_iterator, front_insert_iterator, Insert Iterators

### Standards Conformance

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