ceph/src/boost/libs/mpl/doc/src/refmanual/advance.rst

   1 .. Iterators/Iterator Metafunctions//advance |10
   2
   3 advance
   4 =======
   5
   6 Synopsis
   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
  22 Description
  23 -----------
  24
  25 Moves ``Iterator`` by the distance ``N``. For |bidirectional| and
  26 |random access| iterators, the distance may be negative.
  27
  28
  29 Header
  30 ------
  31
  32 .. parsed-literal::
  33
  34     #include <boost/mpl/advance.hpp>
  35
  36
  37 Parameters
  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
  49 Model Of
  50 --------
  51
  52 |Tag Dispatched Metafunction|
  53
  54
  55 Expression semantics
  56 --------------------
  57
  58 For 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
  98 Complexity
  99 ----------
 100
 101 Amortized constant time if ``iter`` is a model of
 102 |Random Access Iterator|, otherwise linear time.
 103
 104
 105 Example
 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
 121 See 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)