back_insert_iterator<BackInsertionSequence>



Categories: iterators, adaptors	Component type: type

Description

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

Definition

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

Template parameters

Parameter	Description	Default
`BackInsertionSequence`	The type of Back Insertion Sequence into which values will be inserted.

Model of

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

Type requirements

The template parameter BackInsertionSequence must be a Back Insertion Sequence.

Public base classes

None.

Members

Member	Where defined	Description
`back_insert_iterator(BackInsertionSequence&)`	`back_insert_iterator`	See below.
`back_insert_iterator(const back_insert_iterator&)`	Trivial Iterator	The copy constructor
back_insert_iterator& operator=(const back_insert_iterator&)	Trivial Iterator	The assignment operator
`back_insert_iterator& operator*()`	Output Iterator	Used to implement the output iterator expression `*i = x`. [2]
back_insert_iterator& operator=(const BackInsertionSequence::value_type&)	Output Iterator	Used to implement the output iterator expression `*i = x`. [2]
`back_insert_iterator& operator++()`	Output Iterator	Preincrement.
`back_insert_iterator& operator++(int)`	Output Iterator	Postincrement.
output_iterator_tag 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_insert_iterator<BackInsertionSequence> back_inserter(BackInsertionSequence& S)	`back_insert_iterator`	See below.

New members

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.)
template<class BackInsertionSequence> back_insert_iterator<BackInsertionSequence> back_inserter(BackInsertionSequence& S);	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 Sequence S, for example, is reverse_copy(first, last, back_inserter(S)).