Debian Codegraph @

include/deal.II/base/synchronous_iterator.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2009 - 2024 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15 #ifndef dealii_synchronous_iterator_h
16 #define dealii_synchronous_iterator_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/exceptions.h>
22
23 #include <iterator>
24 #include <tuple>
25
26 DEAL_II_NAMESPACE_OPEN
27
28 /**
29 * A class that represents a set of iterators each of which are incremented by
30 * one at the same time. This is typically used in calls like
31 * <code>std::transform(a.begin(), a.end(), b.begin(), functor);</code> where
32 * we have synchronous iterators marching through the containers
33 * <code>a,b</code>. If an object of this type represents the end of a range,
34 * only the first element is considered (we only have <code>a.end()</code>,
35 * not <code>b.end()</code>). An example of how this class is used is given
36 * in step-35.
37 *
38 * The template argument of the current class shall be of type
39 * <code>std::tuple</code> with arguments equal to the iterator types.
40 *
41 * The individual iterators can be accessed using
42 * <code>std::get<X>(synchronous_iterator.iterators)</code> where X is
43 * the number corresponding to the desired iterator.
44 *
45 * This type, and the helper functions associated with it, are used as the
46 * Value concept for the blocked_range type of the Threading Building Blocks.
47 */
48 template <typename Iterators>
49 struct SynchronousIterators
50 {
51 /**
52 * Constructor.
53 */
54 SynchronousIterators(const Iterators &i);
55
56 /**
57 * Dereference const operator. Returns a const reference to the iterators
58 * represented by the current class.
59 */
60 const Iterators &
61 operator*() const;
62
63 /**
64 * Dereference operator. Returns a reference to the iterators
65 * represented by the current class.
66 */
67 Iterators &
68 operator*();
69
70 /**
71 * The following traits are necessary for std::distance() to
72 * work with SynchronousIterators.
73 */
74 using difference_type = std::size_t;
75 using iterator_category = std::bidirectional_iterator_tag;
76 using value_type = Iterators;
77 using pointer = Iterators *;
78 using reference = Iterators &;
79
80 private:
81 /**
82 * Storage for the iterators represented by the current class.
83 */
84 Iterators iterators;
85 };
86
87
88
89 template <typename Iterators>
90 inline SynchronousIterators<Iterators>::SynchronousIterators(const Iterators &i)
91 : iterators(i)
92 {}
93
94
95
96 template <typename Iterators>
97 inline const Iterators &
98 SynchronousIterators<Iterators>::operator*() const
99 {
100 return iterators;
101 }
102
103
104
105 template <typename Iterators>
106 inline Iterators &
107 SynchronousIterators<Iterators>::operator*()
108 {
109 return iterators;
110 }
111
112
113
114 /**
115 * Return whether the first element of the first argument is less than the
116 * first element of the second argument. Since the objects compared march
117 * forward all elements at the same time, comparing the first element is
118 * sufficient.
119 *
120 * @relatesalso SynchronousIterators
121 */
122 template <typename Iterators>
123 inline bool
124 operator<(const SynchronousIterators<Iterators> &a,
125 const SynchronousIterators<Iterators> &b)
126 {
127 return std::get<0>(*a) < std::get<0>(*b);
128 }
129
130
131
132 /**
133 * Return the distance between the first and the second argument. Since the
134 * objects compared march forward all elements at the same time, differencing
135 * the first element is sufficient.
136 *
137 * @relatesalso SynchronousIterators
138 */
139 template <typename Iterators>
140 inline std::size_t
141 operator-(const SynchronousIterators<Iterators> &a,
142 const SynchronousIterators<Iterators> &b)
143 {
144 Assert(std::distance(std::get<0>(*b), std::get<0>(*a)) >= 0,
145 ExcInternalError());
146 return std::distance(std::get<0>(*b), std::get<0>(*a));
147 }
148
149
150 /**
151 * Advance a tuple of iterators by $n$.
152 *
153 * @relatesalso SynchronousIterators
154 */
155 template <typename I1, typename I2>
156 inline void
157 advance(std::tuple<I1, I2> &t, const unsigned int n)
158 {
159 std::advance(std::get<0>(t), n);
160 std::advance(std::get<1>(t), n);
161 }
162
163 /**
164 * Advance a tuple of iterators by $n$.
165 *
166 * @relatesalso SynchronousIterators
167 */
168 template <typename I1, typename I2, typename I3>
169 inline void
170 advance(std::tuple<I1, I2, I3> &t, const unsigned int n)
171 {
172 std::advance(std::get<0>(t), n);
173 std::advance(std::get<1>(t), n);
174 std::advance(std::get<2>(t), n);
175 }
176
177 /**
178 * Advance a tuple of iterators by $n$.
179 *
180 * @relatesalso SynchronousIterators
181 */
182 template <typename I1, typename I2, typename I3, typename I4>
183 inline void
184 advance(std::tuple<I1, I2, I3, I4> &t, const unsigned int n)
185 {
186 std::advance(std::get<0>(t), n);
187 std::advance(std::get<1>(t), n);
188 std::advance(std::get<2>(t), n);
189 std::advance(std::get<3>(t), n);
190 }
191
192 /**
193 * Reverse a tuple of iterators by 1.
194 *
195 * @relatesalso SynchronousIterators
196 */
197 template <typename I1, typename I2>
198 inline void
199 prev(std::tuple<I1, I2> &t)
200 {
201 --std::get<0>(t);
202 --std::get<1>(t);
203 }
204
205 /**
206 * Reverse a tuple of iterators by 1.
207 *
208 * @relatesalso SynchronousIterators
209 */
210 template <typename I1, typename I2, typename I3>
211 inline void
212 prev(std::tuple<I1, I2, I3> &t)
213 {
214 --std::get<0>(t);
215 --std::get<1>(t);
216 --std::get<2>(t);
217 }
218
219 /**
220 * Reverse a tuple of iterators by 1.
221 *
222 * @relatesalso SynchronousIterators
223 */
224 template <typename I1, typename I2, typename I3, typename I4>
225 inline void
226 prev(std::tuple<I1, I2, I3, I4> &t)
227 {
228 --std::get<0>(t);
229 --std::get<1>(t);
230 --std::get<2>(t);
231 --std::get<3>(t);
232 }
233
234 /**
235 * Advance a tuple of iterators by 1.
236 *
237 * @relatesalso SynchronousIterators
238 */
239 template <typename I1, typename I2>
240 inline void
241 advance_by_one(std::tuple<I1, I2> &t)
242 {
243 ++std::get<0>(t);
244 ++std::get<1>(t);
245 }
246
247 /**
248 * Advance a tuple of iterators by 1.
249 *
250 * @relatesalso SynchronousIterators
251 */
252 template <typename I1, typename I2, typename I3>
253 inline void
254 advance_by_one(std::tuple<I1, I2, I3> &t)
255 {
256 ++std::get<0>(t);
257 ++std::get<1>(t);
258 ++std::get<2>(t);
259 }
260
261 /**
262 * Advance a tuple of iterators by 1.
263 *
264 * @relatesalso SynchronousIterators
265 */
266 template <typename I1, typename I2, typename I3, typename I4>
267 inline void
268 advance_by_one(std::tuple<I1, I2, I3, I4> &t)
269 {
270 ++std::get<0>(t);
271 ++std::get<1>(t);
272 ++std::get<2>(t);
273 ++std::get<3>(t);
274 }
275
276 /**
277 * Advance the elements of this iterator by $n$.
278 *
279 * @relatesalso SynchronousIterators
280 */
281 template <typename Iterators>
282 inline SynchronousIterators<Iterators>
283 operator+(const SynchronousIterators<Iterators> &a, const std::size_t n)
284 {
285 SynchronousIterators<Iterators> x(a);
286 dealii::advance(*x, n);
287 return x;
288 }
289
290 /**
291 * Advance the elements of this iterator by 1 (pre-increment).
292 *
293 * @relatesalso SynchronousIterators
294 */
295 template <typename Iterators>
296 inline SynchronousIterators<Iterators> &
297 operator++(SynchronousIterators<Iterators> &a)
298 {
299 dealii::advance_by_one(*a);
300 return a;
301 }
302
303 /**
304 * Reverse the elements of this iterator by 1 (pre-decrement).
305 *
306 * @relatesalso SynchronousIterators
307 */
308 template <typename Iterators>
309 inline SynchronousIterators<Iterators> &
310 operator--(SynchronousIterators<Iterators> &a)
311 {
312 dealii::prev(*a);
313 return a;
314 }
315
316 /**
317 * Advance the elements of this iterator by 1 (post-increment).
318 *
319 * @relatesalso SynchronousIterators
320 */
321 template <typename Iterators>
322 inline SynchronousIterators<Iterators>
323 operator++(SynchronousIterators<Iterators> &a, int)
324 {
325 SynchronousIterators<Iterators> b = a;
326 dealii::advance_by_one(*a);
327 return b;
328 }
329
330 /**
331 * Compare synch iterators for inequality. Since they march in synch,
332 * comparing only the first element is sufficient.
333 *
334 * @relatesalso SynchronousIterators
335 */
336 template <typename Iterators>
337 inline bool
338 operator!=(const SynchronousIterators<Iterators> &a,
339 const SynchronousIterators<Iterators> &b)
340 {
341 return (std::get<0>(*a) != std::get<0>(*b));
342 }
343
344 DEAL_II_NAMESPACE_CLOSE
345
346 #endif