stlab.adobe.com Adobe Systems Incorporated

front_insert_iterator

iterators.gif
type.gif
adaptors.gif
Categories : iterators, adaptors Component type: type

Description

Front_insert_iterator is an iterator adaptor that functions as an OutputIterator : assignment through a front_insert_iterator inserts an object before the first element of a FrontInsertionSequence. [1] [2]

Example

List<int> L;
L.push_front(3);
front_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 2 1 0 3

Definition

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

Template parameters

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

Model of

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

Type requirements

The template parameter FrontInsertionSequence must be a FrontInsertionSequence.

Public base classes

None.

Members

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

New members

These members are not defined in the OutputIterator requirements, but are specific to front_insert_iterator.

Member Description
front_insert_iterator(FrontInsertionSequence& S) Constructs a front_insert_iterator that inserts objects before the first element of S.
template<class FrontInsertionSequence>
front_insert_iterator<FrontInsertionSequence>
front_inserter(FrontInsertionSequence& S);
Equivalent to front_insert_iterator<FrontInsertionSequence>(S). [4] This is a global function, not a member function.

Notes

[1] Note the difference between assignment through a FrontInsertionSequence iterator and assignment through an front_insert_iterator<FrontInsertionSequence>. If i is a valid FrontInsertionSequence iterator, then it points to some particular element in the FrontInsertionSequence; the expression *i = t replaces that element with t, and does not change the total number of elements in the sequence. If ii is a valid front_insert_iterator<FrontInsertionSequence>, however, then the expression *ii = t is equivalent, for some FrontInsertionSequence seq, to the expression seq.push_front(t). That is, it does not overwrite any of seq's elements and it does change seq's size.

[2] Note the difference between a front_insert_iterator and an insert_iterator. It may seem that a front_insert_iterator is the same as an insert_iterator constructed with an insertion point that is the beginning of a sequence. In fact, though, there is a very important difference : every assignment through a front_insert_iterator corresponds to an insertion before the first element of the sequence. If you are inserting elements at the beginning of a sequence using an insert_iterator, then the elements will appear in the order in which they were inserted. If, however, you are inserting elements at the beginning of a sequence using a front_insert_iterator, then the elements will appear in the reverse of the order in which they were inserted.

[3] Note how assignment through an front_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 front_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.

[4] 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 front_insert_iterator need not be declared explicitly. One easy way to reverse a range and insert it at the beginning of a FrontInsertionSequence S, for example, is copy(first, last, front_inserter(S)).

See also

insert_iterator, back_insert_iterator, OutputIterator, Sequence, FrontInsertionSequence, 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