ceph/src/boost/libs/iterator/doc/transform_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 .. Version 1.3 of this document was accepted for TR1
   6
   7 ::
   8
   9   template <class UnaryFunction,
  10             class Iterator,
  11             class Reference = use_default,
  12             class Value = use_default>
  13   class transform_iterator
  14   {
  15   public:
  16     typedef /* see below */ value_type;
  17     typedef /* see below */ reference;
  18     typedef /* see below */ pointer;
  19     typedef iterator_traits<Iterator>::difference_type difference_type;
  20     typedef /* see below */ iterator_category;
  21
  22     transform_iterator();
  23     transform_iterator(Iterator const& x, UnaryFunction f);
  24
  25     template<class F2, class I2, class R2, class V2>
  26     transform_iterator(
  27           transform_iterator<F2, I2, R2, V2> const& t
  28         , typename enable_if_convertible<I2, Iterator>::type* = 0      // exposition only
  29         , typename enable_if_convertible<F2, UnaryFunction>::type* = 0 // exposition only
  30     );
  31     UnaryFunction functor() const;
  32     Iterator const& base() const;
  33     reference operator*() const;
  34     transform_iterator& operator++();
  35     transform_iterator& operator--();
  36   private:
  37     Iterator m_iterator; // exposition only
  38     UnaryFunction m_f;   // exposition only
  39   };
  40
  41
  42 If ``Reference`` is ``use_default`` then the ``reference`` member of
  43 ``transform_iterator`` is
  44 ``result_of<const UnaryFunction(iterator_traits<Iterator>::reference)>::type``.
  45 Otherwise, ``reference`` is ``Reference``.
  46
  47 If ``Value`` is ``use_default`` then the ``value_type`` member is
  48 ``remove_cv<remove_reference<reference> >::type``.  Otherwise,
  49 ``value_type`` is ``Value``.
  50
  51
  52 If ``Iterator`` models Readable Lvalue Iterator and if ``Iterator``
  53 models Random Access Traversal Iterator, then ``iterator_category`` is
  54 convertible to ``random_access_iterator_tag``. Otherwise, if
  55 ``Iterator`` models Bidirectional Traversal Iterator, then
  56 ``iterator_category`` is convertible to
  57 ``bidirectional_iterator_tag``.  Otherwise ``iterator_category`` is
  58 convertible to ``forward_iterator_tag``. If ``Iterator`` does not
  59 model Readable Lvalue Iterator then ``iterator_category`` is
  60 convertible to ``input_iterator_tag``.
  61
  62
  63 ``transform_iterator`` requirements
  64 ...................................
  65
  66 The type ``UnaryFunction`` must be Assignable, Copy Constructible, and
  67 the expression ``f(*i)`` must be valid where ``f`` is a const object of
  68 type ``UnaryFunction``, ``i`` is an object of type ``Iterator``, and
  69 where the type of ``f(*i)`` must be
  70 ``result_of<const UnaryFunction(iterator_traits<Iterator>::reference)>::type``.
  71
  72 The argument ``Iterator`` shall model Readable Iterator.
  73
  74
  75 ``transform_iterator`` models
  76 .............................
  77
  78 The resulting ``transform_iterator`` models the most refined of the
  79 following that is also modeled by ``Iterator``.
  80
  81   * Writable Lvalue Iterator if ``transform_iterator::reference`` is a non-const reference.
  82
  83   * Readable Lvalue Iterator if ``transform_iterator::reference`` is a const reference.
  84
  85   * Readable Iterator otherwise.
  86
  87 The ``transform_iterator`` models the most refined standard traversal
  88 concept that is modeled by the ``Iterator`` argument.
  89
  90 If ``transform_iterator`` is a model of Readable Lvalue Iterator then
  91 it models the following original iterator concepts depending on what
  92 the ``Iterator`` argument models.
  93
  94 +-----------------------------------+---------------------------------------+
  95 | If ``Iterator`` models            | then ``transform_iterator`` models    |
  96 +===================================+=======================================+
  97 | Single Pass Iterator              | Input Iterator                        |
  98 +-----------------------------------+---------------------------------------+
  99 | Forward Traversal Iterator        | Forward Iterator                      |
 100 +-----------------------------------+---------------------------------------+
 101 | Bidirectional Traversal Iterator  | Bidirectional Iterator                |
 102 +-----------------------------------+---------------------------------------+
 103 | Random Access Traversal Iterator  | Random Access Iterator                |
 104 +-----------------------------------+---------------------------------------+
 105
 106 If ``transform_iterator`` models Writable Lvalue Iterator then it is a
 107 mutable iterator (as defined in the old iterator requirements).
 108
 109 ``transform_iterator<F1, X, R1, V1>`` is interoperable with
 110 ``transform_iterator<F2, Y, R2, V2>`` if and only if ``X`` is
 111 interoperable with ``Y``.
 112
 113
 114
 115 ``transform_iterator`` operations
 116 .................................
 117
 118 In addition to the operations required by the concepts modeled by
 119 ``transform_iterator``, ``transform_iterator`` provides the following
 120 operations.
 121
 122
 123 ``transform_iterator();``
 124
 125 :Returns: An instance of ``transform_iterator`` with ``m_f``
 126   and ``m_iterator`` default constructed.
 127
 128
 129 ``transform_iterator(Iterator const& x, UnaryFunction f);``
 130
 131 :Returns: An instance of ``transform_iterator`` with ``m_f``
 132   initialized to ``f`` and ``m_iterator`` initialized to ``x``.
 133
 134
 135 ::
 136
 137     template<class F2, class I2, class R2, class V2>
 138     transform_iterator(
 139           transform_iterator<F2, I2, R2, V2> const& t
 140         , typename enable_if_convertible<I2, Iterator>::type* = 0      // exposition only
 141         , typename enable_if_convertible<F2, UnaryFunction>::type* = 0 // exposition only
 142     );
 143
 144 :Returns: An instance of ``transform_iterator`` with ``m_f``
 145   initialized to ``t.functor()`` and ``m_iterator`` initialized to
 146   ``t.base()``.
 147 :Requires: ``OtherIterator`` is implicitly convertible to ``Iterator``.
 148
 149
 150 ``UnaryFunction functor() const;``
 151
 152 :Returns: ``m_f``
 153
 154
 155 ``Iterator const& base() const;``
 156
 157 :Returns: ``m_iterator``
 158
 159
 160 ``reference operator*() const;``
 161
 162 :Returns: ``m_f(*m_iterator)``
 163
 164
 165 ``transform_iterator& operator++();``
 166
 167 :Effects: ``++m_iterator``
 168 :Returns: ``*this``
 169
 170
 171 ``transform_iterator& operator--();``
 172
 173 :Effects: ``--m_iterator``
 174 :Returns: ``*this``
 175