Standard C++ LibraryCopyright 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



privacy and legal statement