|Categories: iterators, adaptors||Component type: type|
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
|FrontInsertionSequence||The type of Front Insertion Sequence into which values will be inserted.|
|front_insert_iterator(const front_insert_iterator&)||Trivial Iterator||The copy constructor|
front_insert_iterator& operator=(const front_insert_iterator&)
|Trivial Iterator||The assignment operator|
|front_insert_iterator& operator*()||Output Iterator||Used to implement the output iterator expression *i = x. |
front_insert_iterator& operator=(const FrontInsertionSequence::value_type&)
|Output Iterator||Used to implement the output iterator expression *i = x. |
|front_insert_iterator& operator++()||Output Iterator||Preincrement.|
|front_insert_iterator& operator++(int)||Output Iterator||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(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).  This is a global function, not a member function.|
 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 front insertion sequence; 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.
 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.
 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.
 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 Front Insertion Sequence S, for example, is copy(first, last, front_inserter(S)).