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

   1 .. 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 .. Version 1.4 of this ReStructuredText document corresponds to
   6    n1530_, the paper accepted by the LWG for TR1.
   7
   8 .. Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003.
   9
  10 .. parsed-literal::
  11
  12   template <
  13       class Derived
  14     , class Base
  15     , class Value               = use_default
  16     , class CategoryOrTraversal = use_default
  17     , class Reference           = use_default
  18     , class Difference = use_default
  19   >
  20   class iterator_adaptor
  21     : public iterator_facade<Derived, *V'*, *C'*, *R'*, *D'*> // see details__
  22   {
  23       friend class iterator_core_access;
  24    public:
  25       iterator_adaptor();
  26       explicit iterator_adaptor(Base const& iter);
  27       typedef Base base_type;
  28       Base const& base() const;
  29    protected:
  30       typedef iterator_adaptor iterator_adaptor\_;
  31       Base const& base_reference() const;
  32       Base& base_reference();
  33    private: // Core iterator interface for iterator_facade.
  34       typename iterator_adaptor::reference dereference() const;
  35
  36       template <
  37       class OtherDerived, class OtherIterator, class V, class C, class R, class D
  38       >
  39       bool equal(iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& x) const;
  40
  41       void advance(typename iterator_adaptor::difference_type n);
  42       void increment();
  43       void decrement();
  44
  45       template <
  46           class OtherDerived, class OtherIterator, class V, class C, class R, class D
  47       >
  48       typename iterator_adaptor::difference_type distance_to(
  49           iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& y) const;
  50
  51    private:
  52       Base m_iterator; // exposition only
  53   };
  54
  55 __ base_parameters_
  56
  57 .. _requirements:
  58
  59 ``iterator_adaptor`` requirements
  60 ---------------------------------
  61
  62 ``static_cast<Derived*>(iterator_adaptor*)`` shall be well-formed.
  63 The ``Base`` argument shall be Assignable and Copy Constructible.
  64
  65
  66 .. _base_parameters:
  67
  68 ``iterator_adaptor`` base class parameters
  69 ------------------------------------------
  70
  71 The *V'*, *C'*, *R'*, and *D'* parameters of the ``iterator_facade``
  72 used as a base class in the summary of ``iterator_adaptor``
  73 above are defined as follows:
  74
  75 .. parsed-literal::
  76
  77    *V'* = if (Value is use_default)
  78              return iterator_traits<Base>::value_type
  79          else
  80              return Value
  81
  82    *C'* = if (CategoryOrTraversal is use_default)
  83              return iterator_traversal<Base>::type
  84          else
  85              return CategoryOrTraversal
  86
  87    *R'* = if (Reference is use_default)
  88              if (Value is use_default)
  89                  return iterator_traits<Base>::reference
  90              else
  91                  return Value&
  92          else
  93              return Reference
  94
  95    *D'* = if (Difference is use_default)
  96              return iterator_traits<Base>::difference_type
  97          else
  98              return Difference
  99
 100 .. ``iterator_adaptor`` models
 101    ---------------------------
 102
 103    In order for ``Derived`` to model the iterator concepts corresponding
 104    to ``iterator_traits<Derived>::iterator_category``, the expressions
 105    involving ``m_iterator`` in the specifications of those private member
 106    functions of ``iterator_adaptor`` that may be called by
 107    ``iterator_facade<Derived, V, C, R, D>`` in evaluating any valid
 108    expression involving ``Derived`` in those concepts' requirements.
 109
 110 .. The above is confusing and needs a rewrite. -JGS
 111 .. That's why it's removed.  We're embracing inheritance, remember?
 112
 113 ``iterator_adaptor`` public operations
 114 --------------------------------------
 115
 116 ``iterator_adaptor();``
 117
 118 :Requires: The ``Base`` type must be Default Constructible.
 119 :Returns: An instance of ``iterator_adaptor`` with
 120     ``m_iterator`` default constructed.
 121
 122
 123 ``explicit iterator_adaptor(Base const& iter);``
 124
 125 :Returns: An instance of ``iterator_adaptor`` with
 126     ``m_iterator`` copy constructed from ``iter``.
 127
 128 ``Base const& base() const;``
 129
 130 :Returns: ``m_iterator``
 131
 132 ``iterator_adaptor`` protected member functions
 133 -----------------------------------------------
 134
 135 ``Base const& base_reference() const;``
 136
 137 :Returns: A const reference to ``m_iterator``.
 138
 139
 140 ``Base& base_reference();``
 141
 142 :Returns: A non-const reference to ``m_iterator``.
 143
 144
 145 ``iterator_adaptor`` private member functions
 146 ---------------------------------------------
 147
 148 ``typename iterator_adaptor::reference dereference() const;``
 149
 150 :Returns: ``*m_iterator``
 151
 152 ::
 153
 154   template <
 155   class OtherDerived, class OtherIterator, class V, class C, class R, class D
 156   >
 157   bool equal(iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& x) const;
 158
 159 :Returns: ``m_iterator == x.base()``
 160
 161
 162 ``void advance(typename iterator_adaptor::difference_type n);``
 163
 164 :Effects: ``m_iterator += n;``
 165
 166 ``void increment();``
 167
 168 :Effects: ``++m_iterator;``
 169
 170 ``void decrement();``
 171
 172 :Effects: ``--m_iterator;``
 173
 174 ::
 175
 176   template <
 177       class OtherDerived, class OtherIterator, class V, class C, class R, class D
 178   >
 179   typename iterator_adaptor::difference_type distance_to(
 180       iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& y) const;
 181
 182 :Returns: ``y.base() - m_iterator``