]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 |