Module: Standard C++ Library 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
Copyright (c) 1994-2006 Rogue Wave Software, a Quovadx Division.
Licensed under the Apache License, Version 2.0.
Contact Rogue Wave about documentation or support issues. You can also seek help from other developers through the Apache stdcxx community (see below).