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

 NAME

   back_insert_iterator,	back_inserter  - An insert iterator used to
   insert items	at the end of a	collection.

 SYNOPSIS

   #include <iterator>

   template <class Container>
   class	back_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	back_insert_iterator is	used to	insert
   items at	the end	of a collection.	 The function
   back_inserter creates an instance	of a back_insert_iterator for
   a particular	collection type.  A back_insert_iterator can be used
   with	vectors, deques, and lists, but	not with maps or sets.

 INTERFACE

   template <class Container>
   class	back_insert_iterator : public output_iterator {

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

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

 CONSTRUCTOR

   back_insert_iterator (Container& x); Constructor.  Creates an
   instance of a back_insert_iterator associated with container x.

 OPERATORS

   back_insert_iterator<Container>& operator= (const
   Container::value_type& value); Inserts a copy of value on	the
   end	of the container, and returns *this.

   back_insert_iterator<Container>&
   operator* ();
      Returns *this.

   back_insert_iterator<Container>&
   operator++ ();
   back_insert_iterator<Container>
   operator++ (int);
      Increments	the input iterator and returns *this.

 HELPER FUNCTION

   template <class Container> back_insert_iterator<Container>
   back_inserter	(Container& x) Returns a back_insert_iterator that
   will insert elements at the end of container x.  This	function
   allows	you to create insert iterators inline.

 EXAMPLE

   //
   // ins_itr.cpp
   //
    #include <iterator>
    #include <deque>
    #include <iostream.h>

   int main ()
    {
      //
      //	Initialize a deque using an array.
      //
     int	arr[4] = { 3,4,7,8 };
     deque<int> d(arr+0,	arr+4);
      //
      //	Output the original deque.
      //
     cout << "Start with	a deque: " << endl << "	    ";
     copy(d.begin(), d.end(),
 	 ostream_iterator<int,char>(cout," "));
      //
      //	Insert into the	middle.
      //
     insert_iterator<deque<int> > ins(d,	d.begin()+2);
      *ins = 5; *ins = 6;
      //
      //	Output the new deque.
      //
     cout << endl << endl;
     cout << "Use an insert_iterator: " << endl << "	";
     copy(d.begin(), d.end(),
 	 ostream_iterator<int,char>(cout," "));
      //
      //	A deque	of four	1s.
      //
     deque<int> d2(4, 1);
      //
      //	Insert d2 at front of d.
      //
     copy(d2.begin(), d2.end(), front_inserter(d));
      //
      //	Output the new deque.
      //
     cout << endl << endl;
     cout << "Use a front_inserter: " <<	endl <<	"     ";
     copy(d.begin(), d.end(),
 	 ostream_iterator<int,char>(cout," "));
      //
      //	Insert d2 at back of d.
      //
      copy(d2.begin(), d2.end(),	back_inserter(d));
      //
      //	Output the new deque.
      //
     cout << endl << endl;
     cout << "Use a back_inserter: " << endl << "     ";
     copy(d.begin(), d.end(),
 	 ostream_iterator<int,char>(cout," "));
     cout << endl;

     return 0;
    }

   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

 WARNING

   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

   insert iterators

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