Back_insert_iterator is an iterator adaptor that functions as an
Output Iterator: assignment through a back_insert_iterator inserts
an object after the last element of a Back Insertion Sequence. [1]
Example
list<int> L;
L.push_front(3);
back_insert_iterator<list<int> > ii(L);
*ii++ = 0;
*ii++ = 1;
*ii++ = 2;
copy(L.begin(), L.end(), ostream_iterator<int>(cout, " "));
// The values that are printed are 3 0 1 2
These members are not defined
in the Output Iterator requirements,
but are specific to back_insert_iterator.
Member function
Description
back_insert_iterator(BackInsertionSequence& S)
Constructs a back_insert_iterator that inserts objects
after the last element of S. (That is, it inserts objects
just before S's past-the-end iterator.)
Equivalent to back_insert_iterator<BackInsertionSequence>(S). [3]
This is a global function, not a member function.
Notes
[1]
Note the difference between assignment through a
BackInsertionSequence::iterator and assignment through a
back_insert_iterator<BackInsertionSequence>. If i is a valid
BackInsertionSequence::iterator, then it points to some particular
element in the back insertion sequence; the expression *i = t
replaces that element with t, and does not change the total number
of elements in the back insertion sequence. If ii is a valid
back_insert_iterator<BackInsertionSequence>, however, then
the expression *ii = t is equivalent, to the
expression seq.push_back(t). That is, it does not overwrite
any of seq's elements and it does change seq's size.
[2]
Note how assignment through a back_insert_iterator is implemented.
In general, unary operator* must be defined so that it returns a
proxy object, where the proxy object defines operator= to perform
the insert operation. In this case, for the sake of simplicity, the
proxy object is the back_insert_iterator itself. That is, *i simply
returns i, and *i = t is equivalent to i = t. You should not,
however, rely on this behavior. It is an implementation detail,
and it is not guaranteed to remain the same in future versions.
[3]
This function exists solely for the sake of convenience:
since it is a non-member function, the template parameters may be
inferred and the type of the back_insert_iterator need not be declared
explicitly. One easy way to reverse a range and insert it
at the end of a Back Insertion SequenceS, for example, is
reverse_copy(first, last, back_inserter(S)).