ceph/src/boost/libs/iterator/doc/counting_iterator_ref.rst

   1 .. Copyright David Abrahams 2006. Distributed under the Boost
   2 .. Software License, Version 1.0. (See accompanying
   3 .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   4
   5 ::
   6
   7   template <
   8       class Incrementable
   9     , class CategoryOrTraversal = use_default
  10     , class Difference = use_default
  11   >
  12   class counting_iterator
  13   {
  14   public:
  15       typedef Incrementable value_type;
  16       typedef const Incrementable& reference;
  17       typedef const Incrementable* pointer;
  18       typedef /* see below */ difference_type;
  19       typedef /* see below */ iterator_category;
  20
  21       counting_iterator();
  22       counting_iterator(counting_iterator const& rhs);
  23       explicit counting_iterator(Incrementable x);
  24       Incrementable const& base() const;
  25       reference operator*() const;
  26       counting_iterator& operator++();
  27       counting_iterator& operator--();
  28   private:
  29       Incrementable m_inc; // exposition
  30   };
  31
  32
  33 If the ``Difference`` argument is ``use_default`` then
  34 ``difference_type`` is an unspecified signed integral
  35 type. Otherwise ``difference_type`` is ``Difference``.
  36
  37 ``iterator_category`` is determined according to the following
  38 algorithm:
  39
  40 .. parsed-literal::
  41
  42    if (CategoryOrTraversal is not use_default)
  43        return CategoryOrTraversal
  44    else if (numeric_limits<Incrementable>::is_specialized)
  45        return |iterator-category|_\ (
  46            random_access_traversal_tag, Incrementable, const Incrementable&)
  47    else
  48        return |iterator-category|_\ (
  49             iterator_traversal<Incrementable>::type,
  50             Incrementable, const Incrementable&)
  51
  52 [*Note:* implementers are encouraged to provide an implementation of
  53   ``operator-`` and a ``difference_type`` that avoids overflows in
  54   the cases where ``std::numeric_limits<Incrementable>::is_specialized``
  55   is true.]
  56
  57 ``counting_iterator`` requirements
  58 ..................................
  59
  60 The ``Incrementable`` argument shall be Copy Constructible and Assignable.
  61
  62 If ``iterator_category`` is convertible to ``forward_iterator_tag``
  63 or ``forward_traversal_tag``, the following must be well-formed::
  64
  65     Incrementable i, j;
  66     ++i;         // pre-increment
  67     i == j;      // operator equal
  68
  69
  70 If ``iterator_category`` is convertible to
  71 ``bidirectional_iterator_tag`` or ``bidirectional_traversal_tag``,
  72 the following expression must also be well-formed::
  73
  74     --i
  75
  76 If ``iterator_category`` is convertible to
  77 ``random_access_iterator_tag`` or ``random_access_traversal_tag``,
  78 the following must must also be valid::
  79
  80     counting_iterator::difference_type n;
  81     i += n;
  82     n = i - j;
  83     i < j;
  84
  85 ``counting_iterator`` models
  86 ............................
  87
  88 Specializations of ``counting_iterator`` model Readable Lvalue
  89 Iterator. In addition, they model the concepts corresponding to the
  90 iterator tags to which their ``iterator_category`` is convertible.
  91 Also, if ``CategoryOrTraversal`` is not ``use_default`` then
  92 ``counting_iterator`` models the concept corresponding to the iterator
  93 tag ``CategoryOrTraversal``.  Otherwise, if
  94 ``numeric_limits<Incrementable>::is_specialized``, then
  95 ``counting_iterator`` models Random Access Traversal Iterator.
  96 Otherwise, ``counting_iterator`` models the same iterator traversal
  97 concepts modeled by ``Incrementable``.
  98
  99 ``counting_iterator<X,C1,D1>`` is interoperable with
 100 ``counting_iterator<Y,C2,D2>`` if and only if ``X`` is
 101 interoperable with ``Y``.
 102
 103
 104
 105 ``counting_iterator`` operations
 106 ................................
 107
 108 In addition to the operations required by the concepts modeled by
 109 ``counting_iterator``, ``counting_iterator`` provides the following
 110 operations.
 111
 112
 113 ``counting_iterator();``
 114
 115 :Requires: ``Incrementable`` is Default Constructible.
 116 :Effects: Default construct the member ``m_inc``.
 117
 118
 119 ``counting_iterator(counting_iterator const& rhs);``
 120
 121 :Effects: Construct member ``m_inc`` from ``rhs.m_inc``.
 122
 123
 124
 125 ``explicit counting_iterator(Incrementable x);``
 126
 127 :Effects: Construct member ``m_inc`` from ``x``.
 128
 129
 130 ``reference operator*() const;``
 131
 132 :Returns: ``m_inc``
 133
 134
 135 ``counting_iterator& operator++();``
 136
 137 :Effects: ``++m_inc``
 138 :Returns: ``*this``
 139
 140
 141 ``counting_iterator& operator--();``
 142
 143 :Effects: ``--m_inc``
 144 :Returns: ``*this``
 145
 146
 147 ``Incrementable const& base() const;``
 148
 149 :Returns: ``m_inc``