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



privacy and legal statement