# front_insert_iterator<FrontInsertionSequence>

Categories: iterators, adaptors | Component type: type

### Description

`Front_insert_iterator` is an iterator adaptor that functions as an Output Iterator: assignment through a `front_insert_iterator` inserts an object before the first element of a Front Insertion Sequence. [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 Front Insertion Sequence into which values will be inserted. |

### Model of

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

### Type requirements

The template parameter `FrontInsertionSequence` must be a Front Insertion Sequence.

### 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 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`. [3]
    front_insert_iterator&
    operator=(const FrontInsertionSequence::value_type&)
| Output Iterator | Used to implement the output iterator expression `*i = x`. [3]
`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` | See below.

### New members.

These members are not defined in the Output Iterator 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 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.

[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 Front Insertion Sequence `S`, for example, is `copy(first, last, front_inserter(S))`.

### See also

insert_iterator, back_insert_iterator, Output Iterator, Sequence, Front Insertion Sequence, Iterator overview

Copyright © 1999 Silicon Graphics, Inc. All Rights Reserved. TrademarkInformation