Standard C++ Library
Copyright 1998, Rogue Wave Software, Inc.
NAME
back_insert_iterator, back_inserter
- An insert iterator used to insert items at the end of a
collection.
SYNOPSIS
#include <iterator>
template <class Container>
class back_insert_iterator;
DESCRIPTION
Insert iterators let you insert new elements into a collec-
tion rather than copy a new element's value over the value
of an existing element. The class_back_insert_iterator is
used to insert items at the end of a collection. The func-
tion back_inserter creates an instance of a
back_insert_iterator for a particular collection type. A
back_insert_iterator can be used with vectors, deques, and
lists, but not with maps or sets.
INTERFACE
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&);
back_insert_iterator<Container>&
operator=
(const typename Container::const_reference value);
back_insert_iterator<Container>& operator* ();
back_insert_iterator<Container>& operator++ ();
back_insert_iterator<Container> operator++ (int);
};
template <class Container>
back_insert_iterator<Container> back_inserter (Container&);
TYPES
container_type
The type of container acted on by this iterator.
CONSTRUCTORS
explicit
back_insert_iterator (Container& x);
Constructor. Creates an instance of a
back_insert_iterator associated with container x.
OPERATORS
back_insert_iterator<Container>&
operator= (const typename Container::value_type& value);
Inserts a copy of value on the end of the container, and
returns *this.
back_insert_iterator<Container>&
operator* ();
Returns *this.
back_insert_iterator<Container>&
operator++ ();
back_insert_iterator<Container>
operator++ (int);
Increments the input iterator and returns *this.
HELPER FUNCTIONS
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. This function allows you to
create insert iterators inline.
EXAMPLE
//
// ins_itr.cpp
//
#include <iterator>
#include <deque>
#include <iostream>
using namespace std;
int main ()
{
//
// Initialize a deque using an array.
//
int arr[4] = { 3,4,7,8 };
deque<int> d(arr+0, arr+4);
//
// Output the original deque.
//
cout << "Start with a deque: " << endl << " ";
copy(d.begin(), d.end(),
ostream_iterator<int,char>(cout," "));
//
// Insert into the middle.
//
insert_iterator<deque<int> > ins(d, d.begin()+2);
*ins = 5; *ins = 6;
//
// Output the new deque.
//
cout << endl << endl;
cout << "Use an insert_iterator: " << endl << " ";
copy(d.begin(), d.end(),
ostream_iterator<int,char>(cout," "));
//
// A deque of four 1s.
//
deque<int> d2(4, 1);
//
// Insert d2 at front of d.
//
copy(d2.begin(), d2.end(), front_inserter(d));
//
// Output the new deque.
//
cout << endl << endl;
cout << "Use a front_inserter: " << endl << " ";
copy(d.begin(), d.end(),
ostream_iterator<int,char>(cout," "));
//
// Insert d2 at back of d.
//
copy(d2.begin(), d2.end(), back_inserter(d));
//
// Output the new deque.
//
cout << endl << endl;
cout << "Use a back_inserter: " << endl << " ";
copy(d.begin(), d.end(),
ostream_iterator<int,char>(cout," "));
cout << 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
WARNINGS
If your compiler does not support default template parame-
ters, then you always need to supply the Allocator template
argument. For instance, you have to write:
vector<int,allocator<int> >
instead of:
vector<int>
If your compiler does not support namespaces, then you do
not need the using declaration for std.
SEE ALSO
Insert_Iterators