Man Page front_insert_iterator.3

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

NAME

     front_insert_iterator, front_inserter

      - An insert iterator used to insert items at the  beginning
     of a collection.

SYNOPSIS

     #include <iterator>
     template <class Container>
     class front_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_front_insert_iterator  is
     used  to  insert items at the beginning of a collection. The
     function   front_inserter    creates    an    instance    of
     a_front_insert_iterator  for a particular collection type. A
     front_insert_iterator can be used with deques and lists, but
     not with maps or sets.

     Note that a front_insert_iterator makes each element that it
     inserts  the new front of the container. This has the effect
     of reversing the order of the inserted elements.  For  exam-
     ple,  if  you use a front_insert_iterator to insert "1" then
     "2" then "3" onto the front of container  exmpl,  you  find,
     after the three insertions, that the first three elements of
     exmpl are "3 2 1".

INTERFACE

     template <class Container>
     class front_insert_iterator : public
           iterator<output_iterator_tag,void,void,void,void> {
     protected:
       Container* container;
     public:
       typedef Container container_type;
       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>
      front_insert_iterator<Container>
                            front_inserter (Container&);

TYPES

     container_type


        The type of container acted on by this iterator.

CONSTRUCTORS

     explicit
     front_insert_iterator(Container& x);


        Creates an instance of a front_insert_iterator associated
        with container x.

OPERATORS

     front_insert_iterator<Container>&
     operator=(const typename Container::value_type& value);


        Inserts a copy of value on the front  of  the  container,
        and returns *this.



     front_insert_iterator<Container>&
     operator*();


        Returns *this (the input iterator itself).


     front_insert_iterator<Container>&
     operator++();
     front_insert_iterator<Container>
     operator++(int);


        Increments the insert iterator and returns *this.

NON-MEMBER FUNCTIONS

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


        Returns a front_insert_iterator that inserts elements  at
        the beginning of container x. This function allows you to
        create front insert iterators inline.

EXAMPLE

     //
     // ins_itr.cpp
     //
     #include <iterator>
     #include <deque>
     #include <iostream>
     using namespace std;

     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>(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>(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>(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>(cout," "));
       cout << endl;

       return 0;
      }

     Program 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

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:

     deque<int, allocator<int> >

     instead of:

     deque<int>

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

SEE ALSO

     Insert_Iterators