|
|
|
|
| |
| Categories : iterators, adaptors | Component type: type |
Description
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]
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, " "));
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 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
None.
Members
| Member | Where defined | Description |
back_insert_iterator(BackInsertionSequence&) | back_insert_iterator | See below. |
back_insert_iterator(const back_insert_iterator&) | trivial | The copy constructor |
back_insert_iterator&
operator=(const back_insert_iterator&)
| trivial | The assignment operator |
back_insert_iterator& operator*() | OutputIterator | Used to implement the OutputIterator expression *i = x. [2] |
back_insert_iterator&
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. |
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 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_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 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
