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