Module: Standard C++ Library Library: Iterators
back_insert_iteratoriterator
An output iterator used to insert items at the end of a collection
#include <iterator>
namespace std {
template <class Container>
class back_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 specialization back_insert_iterator is used to insert items at the end of a collection. The convenience function template back_inserter() creates an instance of a back_insert_iterator for a particular collection type. A back_insert_iterator can be used with any container that defines the push_back() member function, specifically all sequences (e.g., vector, deque, basic_string, and list), but not with associative containers (e.g., map or set).
namespace std {
template <class Container>
class back_insert_iterator
: public iterator <output_iterator_tag, void, void, void,
void> {
protected:
Container* container;
public:
typedef Container container_type;
explicit back_insert_iterator (container_type&);
back_insert_iterator& operator=
(const typename
container_type::const_reference value);
back_insert_iterator& operator* ();
back_insert_iterator& operator++ ();
back_insert_iterator operator++ (int);
};
template <class Container>
back_insert_iterator<Container> back_inserter(Container&);
}
container_type
The type of container acted on by this iterator.
explicit back_insert_iterator (container_type& x);
Constructor. Creates an instance of a back_insert_iterator associated with container x.
back_insert_iterator& operator= (const typename container_type::constant_reference value);
Inserts a copy of value at the end of the container by calling container->push_back(value), and returns *this.
back_insert_iterator& operator* ();
Returns *this (the iterator itself).
back_insert_iterator& operator* ();
Returns *this.
back_insert_iterator& operator++ (); back_insert_iterator operator++ (int);
Increments the input iterator and returns *this.
template <class Container> back_insert_iterator<Container> back_inserter (Container& x)
Returns a back_insert_iterator that inserts elements at the end 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.1
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).