Library: Iterators
Function
An output iterator used to insert items at the beginning of a collection
#include <iterator>
namespace std {
template <class Container>
class front_insert_iterator;
}
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 template front_insert_iterator is used to insert items at the beginning of a collection. The convenience function template front_inserter() creates an instance of a front_insert_iterator for a particular collection type. A front_insert_iterator can be used with any container that defines the push_front() member function, specifically the sequences deque and list, but not with associative containers (e.g., map or set).
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 find, after the three insertions, that the first three elements of exmpl are "3 2 1".
namespace std {
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_tyep&);
front_insert_iterator&
operator=(typename container_type::const_reference&);
front_insert_iterator& operator*();
front_insert_iterator& operator++();
front_insert_iterator operator++(int);
};
template <class Container>
front_insert_iterator<Container>
front_inserter(Container&);
}
container_type
The type of container acted on by this iterator.
explicit front_insert_iterator(container_type& x);
Creates an instance of a front_insert_iterator associated with container x.
front_insert_iterator<Container>& operator=(typename container_type::constant_reference &value);
Inserts a copy of value at the front of the container by calling container->push_front (value), and returns *this.
front_insert_iterator& operator*();
Returns *this (the iterator itself).
front_insert_iterator& operator++(); front_insert_iterator operator++(int);
Increments the insert iterator and returns *this.
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.
//
// ins_itr.cpp
//
#include <algorithm> // for copy
#include <iostream> // for cout, endl
#include <iterator> // for ostream_iterator, xxx_inserter
#include <deque> // for deque
int main ()
{
// Typedefs for convenience.
typedef std::deque<int, std::allocator<int> > Deque;
typedef std::ostream_iterator<int, char,
std::char_traits<char> > os_iter;
// Initialize a deque using an array.
Deque::value_type arr[] = { 3, 4, 7, 8 };
Deque d (arr, arr + sizeof arr / sizeof *arr);
// Output the original deque.
std::cout << "Start with a deque: \n ";
std::copy (d.begin (), d.end (), os_iter (std::cout, " "));
// Insert into the middle.
std::insert_iterator<Deque> ins (d, d.begin () + 2);
*ins = 5;
*ins = 6;
// Output the new deque.
std::cout << "\n\nUse an insert_iterator: \n ";
std::copy (d.begin (), d.end (), os_iter (std::cout, " "));
// A deque of four 1s.
Deque d2 (4, 1);
// Insert d2 at front of d.
std::copy (d2.begin (), d2.end (),
std::front_inserter (d));
// Output the new deque.
std::cout << "\n\nUse a front_inserter: \n ";
std::copy (d.begin (), d.end (), os_iter (std::cout, " "));
// Insert d2 at back of d.
std::copy (d2.begin (), d2.end (), std::back_inserter (d));
// Output the new deque.
std::cout << "\n\nUse a back_inserter: \n ";
std::copy (d.begin (), d.end (), os_iter (std::cout, " "));
std::cout << std::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
ISO/IEC 14882:1998 -- International Standard for Information Systems -- Programming Language C++, Section 24.4.2.3