The MPL Reference Manual: advance

Front Page / Iterators / Iterator Metafunctions / advance

# advance

### Synopsis

    template<
          typename Iterator
        , typename N
        >
    struct advance
    {
        typedef unspecified type;
    };

### Description

Moves `Iterator` by the distance `N`. For bidirectional and random access iterators, the distance may be negative.

### Header

    #include <boost/mpl/advance.hpp>

### Parameters

Parameter | Requirement | Description
--- | --- | ---
`Iterator` | Forward Iterator | An iterator to advance.
`N` | Integral Constant | A distance.

### Model Of

Tag Dispatched Metafunction

### Expression semantics

For a Forward Iterator `iter` and arbitrary Integral Constant `n`:

    typedef advance<iter,n>::type j;

Return type: | Forward Iterator.
Precondition: | If `Iterator` is a Forward Iterator, `n::value` must be nonnegative.
Semantics: | Equivalent to:
    typedef iter i0;
    typedef next<i0>::type i1;
    ...
    typedef next<in-1>::type j;
if `n::value > 0`, and
    typedef iter i0;
    typedef prior<i0>::type i1;
    ...
    typedef prior<in-1>::type j;
otherwise.
Postcondition: | `j` is dereferenceable or past-the-end; `distance<iter,j>::value == n::value` if `n::value > 0`, and `distance<j,iter>::value == n::value` otherwise.

### Complexity

Amortized constant time if `iter` is a model of Random Access Iterator, otherwise linear time.

### Example

    typedef range_c<int,0,10> numbers;
    typedef begin<numbers>::type first;
    typedef end<numbers>::type last;

    typedef advance<first,int_<10> >::type i1;
    typedef advance<last,int_<-10> >::type i2;

    BOOST_MPL_ASSERT(( boost::is_same<i1,last> ));
    BOOST_MPL_ASSERT(( boost::is_same<i2,first> ));

### See also

Iterators, Tag Dispatched Metafunction, distance, next