Adobe Systems Incorporated


Categories : iterators, adaptors Component type: type


Back_insert_iterator is an iterator adaptor that functions as an OutputIterator : assignment through a back_insert_iterator inserts an object after the last element of a BackInsertionSequence. [1]


List<int> L;
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


Defined in the standard header iterator, and in the nonstandard backward-compatibility header iterator.h.

Template parameters

Parameter Description Default
BackInsertionSequence The type of BackInsertionSequence into which values will be inserted.  

Model of

OutputIterator. An insert iterator's set of value types (as defined in the OutputIterator requirements) consists of a single type : BackInsertionSequence::value_type.

Type requirements

The template parameter BackInsertionSequence must be a BackInsertionSequence.

Public base classes



Member Where defined Description
back_insert_iterator(BackInsertionSequence&) back_insert_iterator See below.
back_insert_iterator(const back_insert_iterator&) trivial The copy constructor
operator=(const back_insert_iterator&)
trivial The assignment operator
back_insert_iterator& operator*() OutputIterator Used to implement the OutputIterator expression *i = x. [2]
operator=(const BackInsertionSequence ::value_type&)
OutputIterator Used to implement the OutputIterator expression *i = x. [2]
back_insert_iterator& operator++() OutputIterator Preincrement.
back_insert_iterator& operator++(int) OutputIterator Postincrement.
iterator_category(const back_insert_iterator&)
iterator_tags Returns the iterator's category. This is a global function, not a member.
template<class BackInsertionSequence>
back_inserter(BackInsertionSequence& S)
back_insert_iterator See below.

New members

These members are not defined in the OutputIterator 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.)
template<class BackInsertionSequence>
back_inserter(BackInsertionSequence& S);
Equivalent to back_insert_iterator<BackInsertionSequence>(S). [3] This is a global function, not a member function.


[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 BackInsertionSequence; the expression *i = t replaces that element with t, and does not change the total number of elements in the BackInsertionSequence. 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 BackInsertionSequence S, for example, is reverse_copy(first, last, back_inserter(S)).

See also

insert_iterator, front_insert_iterator, OutputIterator, BackInsertionSequence, Sequence, Iterators

Copyright © 2006-2007 Adobe Systems Incorporated.

Use of this website signifies your agreement to the Terms of Use and Online Privacy Policy.

Search powered by Google