insert_iterator, inserter

     Insert Iterator

Summary

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

Synopsis

Synopsis

#include <iterator>

template <class Container>
class insert_iterator : public output_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 output_iterator {

public:
   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)

Constructor

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

Constructor. 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);

Assignment operator. 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 Function

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

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

Example

 #include <iterator>
 #include <vector>
 #include <iostream.h>

 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>(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>(cout," "));

   return 0;
 }

Warnings

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

vector<int, allocator>

instead of:

vector<int>