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

 NAME

   Insert_Iterators  - Iterator adaptor that allows an iterator to
   insert into a container rather than overwrite elements in	the
   container.

 SYNOPSIS

   #include <iterator>

   template <class Container>
   class	insert_iterator	: public output_iterator;

   template <class Container>
   class	back_insert_iterator:public output_iterator;

   template <class Container>
   class	front_insert_iterator :	public output_iterator;

 DESCRIPTION

   Insert iterators are iterator	adaptors that let an iterator insert
   new elements	into a collection rather than overwrite	existing
   elements when copying to a container.  There are several types of
   insert iterator classes.

   +	  The class back_insert_iterator is used to insert items
        at the	end of a collection.	 The  function back_inserter
        can be used with an iterator	inline,	to create an instance
        of a back_insert_iterator for a particular collection type.

   +	  The class front_insert_iterator is used to insert items
        at the start of	a collection.  The function front_inserter
        creates an instance	of a front_insert_iterator for a
        particular collection type.

   +	  An insert_iterator inserts new items into a collection at
        a location defined by an iterator supplied to the constructor.
        Like the other insert iterators, insert_iterator has a helper
        function called inserter, which takes a collection and an
        iterator into that collection, and creates an instance of
        the insert_iterator.

 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	back_insert_iterator : public output_iterator {

   public:
     explicit back_insert_iterator (Container&);
     back_insert_iterator<Container>&
      operator= (const typename Container::value_type&);
     back_insert_iterator<Container>& operator* ();
     back_insert_iterator<Container>& operator++	();
     back_insert_iterator<Container> operator++ (int);
   };

   template <class Container>
   class	front_insert_iterator :	public output_iterator {

   public:
     explicit front_insert_iterator (Container&);
     front_insert_iterator<Container>&
      operator= (const typename Container::value_type&);
     front_insert_iterator<Container>& operator*	();
     front_insert_iterator<Container>& operator++ ();
     front_insert_iterator<Container> operator++	(int);
   };

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

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

   template <class Container>
   front_insert_iterator<Container> front_inserter (Container&);

 SEE ALSO

   back_insert_iterator,	front_insert_iterator, insert_iterator

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