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());