ceph/src/boost/libs/iterator/doc/indirect_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 Iterator
   9     , class Value = use_default
  10     , class CategoryOrTraversal = use_default
  11     , class Reference = use_default
  12     , class Difference = use_default
  13   >
  14   class indirect_iterator
  15   {
  16    public:
  17       typedef /* see below */ value_type;
  18       typedef /* see below */ reference;
  19       typedef /* see below */ pointer;
  20       typedef /* see below */ difference_type;
  21       typedef /* see below */ iterator_category;
  22
  23       indirect_iterator();
  24       indirect_iterator(Iterator x);
  25
  26       template <
  27           class Iterator2, class Value2, class Category2
  28         , class Reference2, class Difference2
  29       >
  30       indirect_iterator(
  31           indirect_iterator<
  32                Iterator2, Value2, Category2, Reference2, Difference2
  33           > const& y
  34         , typename enable_if_convertible<Iterator2, Iterator>::type* = 0 // exposition
  35       );
  36
  37       Iterator const& base() const;
  38       reference operator*() const;
  39       indirect_iterator& operator++();
  40       indirect_iterator& operator--();
  41   private:
  42      Iterator m_iterator; // exposition
  43   };
  44
  45
  46 The member types of ``indirect_iterator`` are defined according to
  47 the following pseudo-code, where ``V`` is
  48 ``iterator_traits<Iterator>::value_type``
  49
  50 .. parsed-literal::
  51
  52   if (Value is use_default) then
  53       typedef remove_const<pointee<V>::type>::type value_type;
  54   else
  55       typedef remove_const<Value>::type value_type;
  56
  57   if (Reference is use_default) then
  58       if (Value is use_default) then
  59           typedef indirect_reference<V>::type reference;
  60       else
  61           typedef Value& reference;
  62   else
  63       typedef Reference reference;
  64
  65   if (Value is use_default) then
  66       typedef pointee<V>::type\* pointer;
  67   else
  68       typedef Value\* pointer;
  69
  70   if (Difference is use_default)
  71       typedef iterator_traits<Iterator>::difference_type difference_type;
  72   else
  73       typedef Difference difference_type;
  74
  75   if (CategoryOrTraversal is use_default)
  76       typedef *iterator-category* (
  77           iterator_traversal<Iterator>::type,``reference``,``value_type``
  78       ) iterator_category;
  79   else
  80       typedef *iterator-category* (
  81           CategoryOrTraversal,``reference``,``value_type``
  82       ) iterator_category;
  83
  84
  85 ``indirect_iterator`` requirements
  86 ..................................
  87
  88 The expression ``*v``, where ``v`` is an object of
  89 ``iterator_traits<Iterator>::value_type``, shall be valid
  90 expression and convertible to ``reference``.  ``Iterator`` shall
  91 model the traversal concept indicated by ``iterator_category``.
  92 ``Value``, ``Reference``, and ``Difference`` shall be chosen so
  93 that ``value_type``, ``reference``, and ``difference_type`` meet
  94 the requirements indicated by ``iterator_category``.
  95
  96 [Note: there are further requirements on the
  97 ``iterator_traits<Iterator>::value_type`` if the ``Value``
  98 parameter is not ``use_default``, as implied by the algorithm for
  99 deducing the default for the ``value_type`` member.]
 100
 101 ``indirect_iterator`` models
 102 ............................
 103
 104 In addition to the concepts indicated by ``iterator_category``
 105 and by ``iterator_traversal<indirect_iterator>::type``, a
 106 specialization of ``indirect_iterator`` models the following
 107 concepts, Where ``v`` is an object of
 108 ``iterator_traits<Iterator>::value_type``:
 109
 110   * Readable Iterator if ``reference(*v)`` is convertible to
 111     ``value_type``.
 112
 113   * Writable Iterator if ``reference(*v) = t`` is a valid
 114     expression (where ``t`` is an object of type
 115     ``indirect_iterator::value_type``)
 116
 117   * Lvalue Iterator if ``reference`` is a reference type.
 118
 119 ``indirect_iterator<X,V1,C1,R1,D1>`` is interoperable with
 120 ``indirect_iterator<Y,V2,C2,R2,D2>`` if and only if ``X`` is
 121 interoperable with ``Y``.
 122
 123
 124 ``indirect_iterator`` operations
 125 ................................
 126
 127 In addition to the operations required by the concepts described
 128 above, specializations of ``indirect_iterator`` provide the
 129 following operations.
 130
 131
 132 ``indirect_iterator();``
 133
 134 :Requires: ``Iterator`` must be Default Constructible.
 135 :Effects: Constructs an instance of ``indirect_iterator`` with
 136    a default-constructed ``m_iterator``.
 137
 138
 139 ``indirect_iterator(Iterator x);``
 140
 141 :Effects: Constructs an instance of ``indirect_iterator`` with
 142     ``m_iterator`` copy constructed from ``x``.
 143
 144 ::
 145
 146   template <
 147       class Iterator2, class Value2, unsigned Access, class Traversal
 148     , class Reference2, class Difference2
 149   >
 150   indirect_iterator(
 151       indirect_iterator<
 152            Iterator2, Value2, Access, Traversal, Reference2, Difference2
 153       > const& y
 154     , typename enable_if_convertible<Iterator2, Iterator>::type* = 0 // exposition
 155   );
 156
 157 :Requires: ``Iterator2`` is implicitly convertible to ``Iterator``.
 158 :Effects: Constructs an instance of ``indirect_iterator`` whose
 159     ``m_iterator`` subobject is constructed from ``y.base()``.
 160
 161
 162 ``Iterator const& base() const;``
 163
 164 :Returns: ``m_iterator``
 165
 166
 167 ``reference operator*() const;``
 168
 169 :Returns:  ``**m_iterator``
 170
 171
 172 ``indirect_iterator& operator++();``
 173
 174 :Effects: ``++m_iterator``
 175 :Returns: ``*this``
 176
 177
 178 ``indirect_iterator& operator--();``
 179
 180 :Effects: ``--m_iterator``
 181 :Returns: ``*this``