1[section:transform Transform Iterator] 2 3The transform iterator adapts an iterator by modifying the 4`operator*` to apply a function object to the result of 5dereferencing the iterator and returning the result. 6 7 8[h2 Example] 9 10 11This is a simple example of using the transform_iterators class to 12generate iterators that multiply (or add to) the value returned by 13dereferencing the iterator. It would be cooler to use lambda library 14in this example. 15 16 int x[] = { 1, 2, 3, 4, 5, 6, 7, 8 }; 17 const int N = sizeof(x)/sizeof(int); 18 19 typedef boost::binder1st< std::multiplies<int> > Function; 20 typedef boost::transform_iterator<Function, int*> doubling_iterator; 21 22 doubling_iterator i(x, boost::bind1st(std::multiplies<int>(), 2)), 23 i_end(x + N, boost::bind1st(std::multiplies<int>(), 2)); 24 25 std::cout << "multiplying the array by 2:" << std::endl; 26 while (i != i_end) 27 std::cout << *i++ << " "; 28 std::cout << std::endl; 29 30 std::cout << "adding 4 to each element in the array:" << std::endl; 31 std::copy(boost::make_transform_iterator(x, boost::bind1st(std::plus<int>(), 4)), 32 boost::make_transform_iterator(x + N, boost::bind1st(std::plus<int>(), 4)), 33 std::ostream_iterator<int>(std::cout, " ")); 34 std::cout << std::endl; 35 36 37The output is: 38 39[pre 40multiplying the array by 2: 412 4 6 8 10 12 14 16 42adding 4 to each element in the array: 435 6 7 8 9 10 11 12 44] 45 46The source code for this example can be found 47[example_link transform_iterator_example.cpp..here]. 48 49[h2 Reference] 50 51 52[h3 Synopsis] 53 54 template <class UnaryFunction, 55 class Iterator, 56 class Reference = use_default, 57 class Value = use_default> 58 class transform_iterator 59 { 60 public: 61 typedef /* see below */ value_type; 62 typedef /* see below */ reference; 63 typedef /* see below */ pointer; 64 typedef iterator_traits<Iterator>::difference_type difference_type; 65 typedef /* see below */ iterator_category; 66 67 transform_iterator(); 68 transform_iterator(Iterator const& x, UnaryFunction f); 69 70 template<class F2, class I2, class R2, class V2> 71 transform_iterator( 72 transform_iterator<F2, I2, R2, V2> const& t 73 , typename enable_if_convertible<I2, Iterator>::type* = 0 // exposition only 74 , typename enable_if_convertible<F2, UnaryFunction>::type* = 0 // exposition only 75 ); 76 UnaryFunction functor() const; 77 Iterator const& base() const; 78 reference operator*() const; 79 transform_iterator& operator++(); 80 transform_iterator& operator--(); 81 private: 82 Iterator m_iterator; // exposition only 83 UnaryFunction m_f; // exposition only 84 }; 85 86 87If `Reference` is `use_default` then the `reference` member of 88`transform_iterator` is[br] 89`result_of<const UnaryFunction(iterator_traits<Iterator>::reference)>::type`. 90Otherwise, `reference` is `Reference`. 91 92 93If `Value` is `use_default` then the `value_type` member is 94`remove_cv<remove_reference<reference> >::type`. Otherwise, 95`value_type` is `Value`. 96 97 98If `Iterator` models Readable Lvalue Iterator and if `Iterator` 99models Random Access Traversal Iterator, then `iterator_category` is 100convertible to `random_access_iterator_tag`. Otherwise, if 101`Iterator` models Bidirectional Traversal Iterator, then 102`iterator_category` is convertible to 103`bidirectional_iterator_tag`. Otherwise `iterator_category` is 104convertible to `forward_iterator_tag`. If `Iterator` does not 105model Readable Lvalue Iterator then `iterator_category` is 106convertible to `input_iterator_tag`. 107 108 109[h3 Requirements] 110 111 112The type `UnaryFunction` must be Assignable, Copy Constructible, and 113the expression `f(*i)` must be valid where `f` is a const object of 114type `UnaryFunction`, `i` is an object of type `Iterator`, and 115where the type of `f(*i)` must be 116`result_of<const UnaryFunction(iterator_traits<Iterator>::reference)>::type`. 117 118 119The argument `Iterator` shall model Readable Iterator. 120 121 122[h3 Concepts] 123 124 125The resulting `transform_iterator` models the most refined of the 126following that is also modeled by `Iterator`. 127 128 129* Writable Lvalue Iterator if `transform_iterator::reference` is a non-const reference. 130 131* Readable Lvalue Iterator if `transform_iterator::reference` is a const reference. 132 133* Readable Iterator otherwise. 134 135 136The `transform_iterator` models the most refined standard traversal 137concept that is modeled by the `Iterator` argument. 138 139 140If `transform_iterator` is a model of Readable Lvalue Iterator then 141it models the following original iterator concepts depending on what 142the `Iterator` argument models. 143 144 145[table Category 146[[If `Iterator` models][then `transform_iterator` models]] 147[[Single Pass Iterator][Input Iterator]] 148[[Forward Traversal Iterator][Forward Iterator]] 149[[Bidirectional Traversal Iterator][Bidirectional Iterator]] 150[[Random Access Traversal Iterator][Random Access Iterator]] 151] 152 153If `transform_iterator` models Writable Lvalue Iterator then it is a 154mutable iterator (as defined in the old iterator requirements). 155 156 157`transform_iterator<F1, X, R1, V1>` is interoperable with 158`transform_iterator<F2, Y, R2, V2>` if and only if `X` is 159interoperable with `Y`. 160 161[h3 Operations] 162 163In addition to the operations required by the [link iterator.specialized.transform.concepts concepts] modeled by 164`transform_iterator`, `transform_iterator` provides the following 165operations: 166 167 transform_iterator(); 168 169[*Returns: ] An instance of `transform_iterator` with `m_f` 170 and `m_iterator` default constructed. 171 172 transform_iterator(Iterator const& x, UnaryFunction f); 173 174[*Returns: ] An instance of `transform_iterator` with `m_f` 175 initialized to `f` and `m_iterator` initialized to `x`. 176 177 template<class F2, class I2, class R2, class V2> 178 transform_iterator( 179 transform_iterator<F2, I2, R2, V2> const& t 180 , typename enable_if_convertible<I2, Iterator>::type* = 0 // exposition only 181 , typename enable_if_convertible<F2, UnaryFunction>::type* = 0 // exposition only 182 ); 183 184[*Returns: ] An instance of `transform_iterator` with `m_f` 185 initialized to `t.functor()` and `m_iterator` initialized to 186 `t.base()`.[br] 187[*Requires: ] `OtherIterator` is implicitly convertible to `Iterator`. 188 189 190 UnaryFunction functor() const; 191 192[*Returns: ] `m_f` 193 194 195 Iterator const& base() const; 196 197[*Returns: ] `m_iterator` 198 199 200 reference operator*() const; 201 202[*Returns: ] `m_f(*m_iterator)` 203 204 205 transform_iterator& operator++(); 206 207[*Effects: ] `++m_iterator`[br] 208[*Returns: ] `*this` 209 210 211 transform_iterator& operator--(); 212 213[*Effects: ] `--m_iterator`[br] 214[*Returns: ] `*this` 215 216[endsect] 217