# advance

Categories: algorithms, iterators | Component type: function

### Prototype

    template <class InputIterator, class Distance>
    void advance(InputIterator& i, Distance n);

### Description

`Advance(i, n)` increments the iterator `i` by the distance `n`. If `n > 0` it is equivalent to executing `++i` `n` times, and if `n < 0` it is equivalent to executing `--i` `n` times. If `n == 0`, the call has no effect.

### Definition

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

### Requirements on types

- `InputIterator` is a model of Input Iterator.
- `Distance` is an integral type that is convertible to `InputIterator`'s distance type.

### Preconditions

- `i` is nonsingular.
- Every iterator between `i` and `i+n` (inclusive) is nonsingular.
- If `InputIterator` is a model of input iterator or forward iterator, then `n` must be nonnegative. If `InputIterator` is a model of bidirectional iterator or random access iterator, then this precondition does not apply.

### Complexity

Constant time if `InputIterator` is a model of random access iterator, otherwise linear time.

### Example

    list<int> L;
    L.push_back(0);
    L.push_back(1);

    list<int>::iterator i = L.begin();
    advance(i, 2);
    assert(i == L.end());

### Notes

### See also

`distance`, Input iterator, Bidirectional Iterator, Random access iterator, `iterator_traits`, Iterator overview.

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