Standard C++	Library
 		 Copyright 1996, Rogue Wave Software, Inc.

 NAME

   insert_iterator, inserter  - An insert iterator used to insert items
   into a collection rather than overwrite the collection.

 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,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 need to always supply	the Allocator template argument.  For
   instance, you'll have to write:

   vector<int, allocator<int> >

   instead of:

   vector<int>

 SEE ALSO

   back_insert_iterator,	front_insert_iterator, Insert Iterators

 STANDARDS CONFORMANCE
   ANSI X3J16/ISO WG21 Joint C++	Committee