front_inserter (3C++std) - Tru64 UNIX
Standard C++ LibraryCopyright 1996, 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 : 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 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 example, if you use a front_insert_iterator to
insert "1" then "2" then "3" onto the front of container exmpl, you will
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 output_iterator {
public:
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&);
CONSTRUCTOR
explicit
front_insert_iterator(Container& x);
Constructor. Creates an instance of a front_insert_iterator associated
with container x.
OPERATORS
front_insert_iterator<Container>&
operator=(const typename Container::value_type& value);
Assignment Operator. 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 FUNCTION
template <class Container>
front_insert_iterator<Container>
front_inserter(Container& x)
Returns a front_insert_iterator that will insert 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.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>(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;
}
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 parameters then you need
to always supply the Allocator template argument. For instance you'll have
to write:
deque<int, allocator<int> >
instead of:
deque<int>
SEE ALSO
Insert Iterators
STANDARDS CONFORMANCE
ANSI X3J16/ISO WG21 Joint C++ Committee
privacy and legal statement