]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | .. 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.4 of this ReStructuredText document corresponds to | |
6 | n1530_, the paper accepted by the LWG for TR1. | |
7 | ||
8 | .. Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. | |
9 | ||
10 | .. parsed-literal:: | |
11 | ||
12 | template < | |
13 | class Derived | |
14 | , class Base | |
15 | , class Value = use_default | |
16 | , class CategoryOrTraversal = use_default | |
17 | , class Reference = use_default | |
18 | , class Difference = use_default | |
19 | > | |
20 | class iterator_adaptor | |
21 | : public iterator_facade<Derived, *V'*, *C'*, *R'*, *D'*> // see details__ | |
22 | { | |
23 | friend class iterator_core_access; | |
24 | public: | |
25 | iterator_adaptor(); | |
26 | explicit iterator_adaptor(Base const& iter); | |
27 | typedef Base base_type; | |
28 | Base const& base() const; | |
29 | protected: | |
30 | typedef iterator_adaptor iterator_adaptor\_; | |
31 | Base const& base_reference() const; | |
32 | Base& base_reference(); | |
33 | private: // Core iterator interface for iterator_facade. | |
34 | typename iterator_adaptor::reference dereference() const; | |
35 | ||
36 | template < | |
37 | class OtherDerived, class OtherIterator, class V, class C, class R, class D | |
38 | > | |
39 | bool equal(iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& x) const; | |
40 | ||
41 | void advance(typename iterator_adaptor::difference_type n); | |
42 | void increment(); | |
43 | void decrement(); | |
44 | ||
45 | template < | |
46 | class OtherDerived, class OtherIterator, class V, class C, class R, class D | |
47 | > | |
48 | typename iterator_adaptor::difference_type distance_to( | |
49 | iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& y) const; | |
50 | ||
51 | private: | |
52 | Base m_iterator; // exposition only | |
53 | }; | |
54 | ||
55 | __ base_parameters_ | |
56 | ||
57 | .. _requirements: | |
58 | ||
59 | ``iterator_adaptor`` requirements | |
60 | --------------------------------- | |
61 | ||
62 | ``static_cast<Derived*>(iterator_adaptor*)`` shall be well-formed. | |
63 | The ``Base`` argument shall be Assignable and Copy Constructible. | |
64 | ||
65 | ||
66 | .. _base_parameters: | |
67 | ||
68 | ``iterator_adaptor`` base class parameters | |
69 | ------------------------------------------ | |
70 | ||
71 | The *V'*, *C'*, *R'*, and *D'* parameters of the ``iterator_facade`` | |
72 | used as a base class in the summary of ``iterator_adaptor`` | |
73 | above are defined as follows: | |
74 | ||
75 | .. parsed-literal:: | |
76 | ||
77 | *V'* = if (Value is use_default) | |
78 | return iterator_traits<Base>::value_type | |
79 | else | |
80 | return Value | |
81 | ||
82 | *C'* = if (CategoryOrTraversal is use_default) | |
83 | return iterator_traversal<Base>::type | |
84 | else | |
85 | return CategoryOrTraversal | |
86 | ||
87 | *R'* = if (Reference is use_default) | |
88 | if (Value is use_default) | |
89 | return iterator_traits<Base>::reference | |
90 | else | |
91 | return Value& | |
92 | else | |
93 | return Reference | |
94 | ||
95 | *D'* = if (Difference is use_default) | |
96 | return iterator_traits<Base>::difference_type | |
97 | else | |
98 | return Difference | |
99 | ||
100 | .. ``iterator_adaptor`` models | |
101 | --------------------------- | |
102 | ||
103 | In order for ``Derived`` to model the iterator concepts corresponding | |
104 | to ``iterator_traits<Derived>::iterator_category``, the expressions | |
105 | involving ``m_iterator`` in the specifications of those private member | |
106 | functions of ``iterator_adaptor`` that may be called by | |
107 | ``iterator_facade<Derived, V, C, R, D>`` in evaluating any valid | |
108 | expression involving ``Derived`` in those concepts' requirements. | |
109 | ||
110 | .. The above is confusing and needs a rewrite. -JGS | |
111 | .. That's why it's removed. We're embracing inheritance, remember? | |
112 | ||
113 | ``iterator_adaptor`` public operations | |
114 | -------------------------------------- | |
115 | ||
116 | ``iterator_adaptor();`` | |
117 | ||
118 | :Requires: The ``Base`` type must be Default Constructible. | |
119 | :Returns: An instance of ``iterator_adaptor`` with | |
120 | ``m_iterator`` default constructed. | |
121 | ||
122 | ||
123 | ``explicit iterator_adaptor(Base const& iter);`` | |
124 | ||
125 | :Returns: An instance of ``iterator_adaptor`` with | |
126 | ``m_iterator`` copy constructed from ``iter``. | |
127 | ||
128 | ``Base const& base() const;`` | |
129 | ||
130 | :Returns: ``m_iterator`` | |
131 | ||
132 | ``iterator_adaptor`` protected member functions | |
133 | ----------------------------------------------- | |
134 | ||
135 | ``Base const& base_reference() const;`` | |
136 | ||
137 | :Returns: A const reference to ``m_iterator``. | |
138 | ||
139 | ||
140 | ``Base& base_reference();`` | |
141 | ||
142 | :Returns: A non-const reference to ``m_iterator``. | |
143 | ||
144 | ||
145 | ``iterator_adaptor`` private member functions | |
146 | --------------------------------------------- | |
147 | ||
148 | ``typename iterator_adaptor::reference dereference() const;`` | |
149 | ||
150 | :Returns: ``*m_iterator`` | |
151 | ||
152 | :: | |
153 | ||
154 | template < | |
155 | class OtherDerived, class OtherIterator, class V, class C, class R, class D | |
156 | > | |
157 | bool equal(iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& x) const; | |
158 | ||
159 | :Returns: ``m_iterator == x.base()`` | |
160 | ||
161 | ||
162 | ``void advance(typename iterator_adaptor::difference_type n);`` | |
163 | ||
164 | :Effects: ``m_iterator += n;`` | |
165 | ||
166 | ``void increment();`` | |
167 | ||
168 | :Effects: ``++m_iterator;`` | |
169 | ||
170 | ``void decrement();`` | |
171 | ||
172 | :Effects: ``--m_iterator;`` | |
173 | ||
174 | :: | |
175 | ||
176 | template < | |
177 | class OtherDerived, class OtherIterator, class V, class C, class R, class D | |
178 | > | |
179 | typename iterator_adaptor::difference_type distance_to( | |
180 | iterator_adaptor<OtherDerived, OtherIterator, V, C, R, D> const& y) const; | |
181 | ||
182 | :Returns: ``y.base() - m_iterator`` |