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