Man Page inserter.3

                       Standard C++ Library
             Copyright 1998, 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;

DESCRIPTION

     Insert iterators let you insert new elements into a  collec-
     tion  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
          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)

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  loca-
        tion  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 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

      #include <iterator>
      #include <vector>
      #include <iostream>
     using namespace std;
     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  parame-
     ters,  then you always need to supply the Allocator template
     argument. For instance, you have to write:

     vector<int, allocator<int> >

     instead of:

     vector<int>

     If your compiler does not support namespaces,  then  you  do
     not need the using declaration for std.

SEE ALSO

     back_insert_iterator,                 front_insert_iterator,
     Insert_Iterators