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 42If ``Reference`` is ``use_default`` then the ``reference`` member of 43``transform_iterator`` is 44``result_of<const UnaryFunction(iterator_traits<Iterator>::reference)>::type``. 45Otherwise, ``reference`` is ``Reference``. 46 47If ``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 52If ``Iterator`` models Readable Lvalue Iterator and if ``Iterator`` 53models Random Access Traversal Iterator, then ``iterator_category`` is 54convertible 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 58convertible to ``forward_iterator_tag``. If ``Iterator`` does not 59model Readable Lvalue Iterator then ``iterator_category`` is 60convertible to ``input_iterator_tag``. 61 62 63``transform_iterator`` requirements 64................................... 65 66The type ``UnaryFunction`` must be Assignable, Copy Constructible, and 67the expression ``f(*i)`` must be valid where ``f`` is a const object of 68type ``UnaryFunction``, ``i`` is an object of type ``Iterator``, and 69where the type of ``f(*i)`` must be 70``result_of<const UnaryFunction(iterator_traits<Iterator>::reference)>::type``. 71 72The argument ``Iterator`` shall model Readable Iterator. 73 74 75``transform_iterator`` models 76............................. 77 78The resulting ``transform_iterator`` models the most refined of the 79following 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 87The ``transform_iterator`` models the most refined standard traversal 88concept that is modeled by the ``Iterator`` argument. 89 90If ``transform_iterator`` is a model of Readable Lvalue Iterator then 91it models the following original iterator concepts depending on what 92the ``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 106If ``transform_iterator`` models Writable Lvalue Iterator then it is a 107mutable 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 111interoperable with ``Y``. 112 113 114 115``transform_iterator`` operations 116................................. 117 118In addition to the operations required by the concepts modeled by 119``transform_iterator``, ``transform_iterator`` provides the following 120operations. 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 176