1.. Iterators/Iterator Metafunctions//advance |10
2
3advance
4=======
5
6Synopsis
7--------
8
9.. parsed-literal::
10
11    template<
12          typename Iterator
13        , typename N
14        >
15    struct advance
16    {
17        typedef |unspecified| type;
18    };
19
20
21
22Description
23-----------
24
25Moves ``Iterator`` by the distance ``N``. For |bidirectional| and
26|random access| iterators, the distance may be negative.
27
28
29Header
30------
31
32.. parsed-literal::
33
34    #include <boost/mpl/advance.hpp>
35
36
37Parameters
38----------
39
40+---------------+---------------------------+-----------------------------------+
41| Parameter     | Requirement               | Description                       |
42+===============+===========================+===================================+
43| ``Iterator``  | |Forward Iterator|        | An iterator to advance.           |
44+---------------+---------------------------+-----------------------------------+
45| ``N``         | |Integral Constant|       | A distance.                       |
46+---------------+---------------------------+-----------------------------------+
47
48
49Model Of
50--------
51
52|Tag Dispatched Metafunction|
53
54
55Expression semantics
56--------------------
57
58For a |Forward Iterator| ``iter`` and arbitrary |Integral Constant| ``n``:
59
60.. parsed-literal::
61
62    typedef advance<iter,n>::type j;
63
64:Return type:
65    |Forward Iterator|.
66
67:Precondition:
68    If ``Iterator`` is a |Forward Iterator|, ``n::value`` must be nonnegative.
69
70:Semantics:
71    Equivalent to:
72
73    .. parsed-literal::
74
75        typedef iter i0;
76        typedef next<i0>::type i1;
77        |...|
78        typedef next<i\ *n-1*\ >::type j;
79
80    if ``n::value > 0``, and
81
82    .. parsed-literal::
83
84        typedef iter i0;
85        typedef prior<i0>::type i1;
86        |...|
87        typedef prior<i\ *n-1*\ >::type j;
88
89    otherwise.
90
91
92:Postcondition:
93    ``j`` is dereferenceable or past-the-end;
94    ``distance<iter,j>::value == n::value`` if ``n::value > 0``, and
95    ``distance<j,iter>::value == n::value`` otherwise.
96
97
98Complexity
99----------
100
101Amortized constant time if ``iter`` is a model of
102|Random Access Iterator|, otherwise linear time.
103
104
105Example
106-------
107
108.. parsed-literal::
109
110    typedef range_c<int,0,10> numbers;
111    typedef begin<numbers>::type first;
112    typedef end<numbers>::type last;
113
114    typedef advance<first,int_<10> >::type i1;
115    typedef advance<last,int_<-10> >::type i2;
116
117    BOOST_MPL_ASSERT(( boost::is_same<i1,last> ));
118    BOOST_MPL_ASSERT(( boost::is_same<i2,first> ));
119
120
121See also
122--------
123
124|Iterators|, |Tag Dispatched Metafunction|, |distance|, |next|
125
126.. |bidirectional| replace:: `bidirectional`_
127.. _bidirectional: `Bidirectional Iterator`_
128.. |random access| replace:: `random access`_
129.. _random access: `Random Access Iterator`_
130
131
132.. copyright:: Copyright �  2001-2009 Aleksey Gurtovoy and David Abrahams
133   Distributed under the Boost Software License, Version 1.0. (See accompanying
134   file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
135