Library: Iterators
insert_iteratoriterator
insert_iterator is an insert iterator used to insert items into a collection rather than overwrite the collection
#include <iterator>
namespace std {
template <class Container>
class 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 insert_iterator is used to insert items into a specified location of a collection. The function inserter() creates an instance of an insert_iterator given a particular collection type and iterator. An insert_iterator can be used with vectors, deques, lists, maps and sets.
namespace std{
template <class Container>
class insert_iterator : public
iterator<output_iterator_tag,void,void,void,void>; {
protected:
Container* container;
public:
typedef Container container_type;
insert_iterator(Container&, typename Container::iterator);
insert_iterator<Container>&
operator=(const typename Container::value_type&);
insert_iterator<Container>& operator*();
insert_iterator<Container>& operator++();
insert_iterator<Container>& operator++(int);
};
template <class Container, class Iterator>
insert_iterator<Container> inserter(Container&, Iterator)
}
container_type
The type of container acted on by the iterator.
insert_iterator(Container& x,
typename Container::iterator i);
Creates an instance of an insert_iterator associated with container x and iterator i.
insert_iterator<Container>& operator=(const typename Container::value_type& value);
Inserts a copy of value into the container at the location specified by the insert_iterator, increments the iterator, and returns *this.
insert_iterator<Container>& operator*();
Returns *this (the input iterator itself).
insert_iterator<Container>& operator++(); insert_iterator<Container>& operator++(int);
Increments the insert iterator and returns *this.
template <class Container, class Iterator> insert_iterator<Container> inserter(Container& x, Iterator i);
Returns an insert_iterator that inserts elements into container x at location i. This function allows you to create insert iterators inline.
//
// 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
back_insert_iterator, front_insert_iterator, Insert Iterators
ISO/IEC 14882:1998 -- International Standard for Information Systems -- Programming Language C++, Section 24.4.2.5