-
Notifications
You must be signed in to change notification settings - Fork 738
/
iterator_range.h
421 lines (347 loc) · 11.9 KB
/
iterator_range.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
// ---------------------------------------------------------------------
//
// Copyright (C) 2014 - 2020 by the deal.II authors
//
// This file is part of the deal.II library.
//
// The deal.II library is free software; you can use it, redistribute
// it, and/or modify it under the terms of the GNU Lesser General
// Public License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
// The full text of the license can be found in the file LICENSE.md at
// the top level directory of deal.II.
//
// ---------------------------------------------------------------------
#ifndef dealii_iterator_range_h
#define dealii_iterator_range_h
#include <deal.II/base/config.h>
#include <deal.II/base/template_constraints.h>
#include <iterator>
DEAL_II_NAMESPACE_OPEN
// Forward declaration
#ifndef DOXYGEN
template <typename Iterator>
class IteratorOverIterators;
#endif
/**
* A class that is used to denote a collection of iterators that can be
* expressed in terms of a range of iterators characterized by a begin and an
* end iterator. As is common in C++, these ranges are specified as half open
* intervals defined by a begin iterator and a one-past-the-end iterator.
*
* The purpose of this class is so that classes such as Triangulation and
* DoFHandler can return ranges of cell iterators using an object of the
* current type from functions such as
* Triangulation::cell_iterators() and that such an
* object can then be used in a range-based for loop as supported by C++11,
* see also
* @ref CPP11 "C++11 standard".
*
* For example, such a loop could look like this if the goal is to set the
* user flag on every active cell:
* @code
* Triangulation<dim> triangulation;
* ...
* for (auto &cell : triangulation.active_cell_iterators())
* cell->set_user_flag();
* @endcode
* In other words, the <code>cell</code> objects are iterators, and the range
* object returned by Triangulation::active_cell_iterators() and similar
* functions are conceptually thought of as <i>collections of iterators</i>.
*
* Of course, the class may also be used to denote other iterator ranges using
* different kinds of iterators into other containers.
*
*
* <h3>Class design: Motivation</h3>
*
* Informally, the way the C++11 standard describes <a
* href="http://en.wikipedia.org/wiki/C%2B%2B11#Range-based_for_loop">range-
* based for loops</a> works as follows: A <i>range-based for loop</i> of the
* form
* @code
* Container c;
* for (auto v : c)
* statement;
* @endcode
* where <code>c</code> is a container or collection, is equivalent to the
* following loop:
* @code
* Container c;
* for (auto tmp=c.begin(); tmp!=c.end(); ++tmp)
* {
* auto v = *tmp;
* statement;
* }
* @endcode
* (The precise definition can be found here:
* https://en.cppreference.com/w/cpp/language/range-for .)
* In other words, the compiler introduces a temporary variable that
* <i>iterates</i> over the elements of the container or collection, and the
* original variable <code>v</code> that appeared in the range-based for loop
* represents the <i>dereferenced</i> state of these iterators -- namely,
* the <i>elements</i> of the collection.
*
* In the context of loops over cells, we typically want to retain the fact
* that the loop variable is an iterator, not a value. This is because in
* deal.II, we never actually use the <i>dereferenced state</i> of a cell
* iterator: conceptually, it would represent a cell, and technically it is
* implemented by classes such as CellAccessor and DoFCellAccessor, but these
* classes are never used explicitly. Consequently, what we would like is that
* a call such as Triangulation::active_cell_iterators() returns an object
* that represents a <i>collection of iterators</i> of the kind <code>{begin,
* begin+1, ..., end-1}</code>. This is conveniently expressed as the half
* open interval <code>[begin,end)</code>. The loop variable in the range-
* based for loop would then take on each of these iterators in turn.
*
*
* <h3>Class design: Implementation</h3>
*
* To represent the desired semantics as outlined above, this class stores a
* half-open range of iterators <code>[b,e)</code> of the given template type.
* Secondly, the class needs to provide begin() and end() functions in such a
* way that if you <i>dereference</i> the result of IteratorRange::begin(),
* you get the <code>b</code> iterator. Furthermore, you must be able to
* increment the object returned by IteratorRange::begin() so that
* <code>*(++begin()) == b+1</code>. In other words, IteratorRange::begin()
* must return an iterator that when dereferenced returns an iterator of the
* template type <code>Iterator</code>: It is an iterator over iterators in
* the same sense as if you had a pointer into an array of pointers.
*
* This is implemented in the form of the IteratorRange::IteratorOverIterators
* class.
*
* @ingroup CPP11
*/
template <typename Iterator>
class IteratorRange
{
public:
/**
* Typedef for the iterator type that iterates over other iterators.
*/
using IteratorOverIterators = dealii::IteratorOverIterators<Iterator>;
/**
* Typedef for the iterator type represent by this class.
*/
using iterator = Iterator;
/**
* Default constructor. Create a range represented by two default
* constructed iterators. This range is likely (depending on the type of the
* iterators) empty.
*/
IteratorRange();
/**
* Constructor. Constructs a range given the begin and end iterators.
*
* @param[in] begin An iterator pointing to the first element of the range
* @param[in] end An iterator pointing past the last element represented
* by this range.
*/
IteratorRange(const iterator begin, const iterator end);
/**
* Return the iterator pointing to the first element of this range.
*/
IteratorOverIterators
begin();
/**
* Return the iterator pointing to the first element of this range.
*/
IteratorOverIterators
begin() const;
/**
* Return the iterator pointing to the element past the last element of this
* range.
*/
IteratorOverIterators
end() const;
/**
* Return the iterator pointing to the element past the last element of this
* range.
*/
IteratorOverIterators
end();
private:
/**
* Iterators characterizing the begin and end of the range.
*/
const IteratorOverIterators it_begin;
const IteratorOverIterators it_end;
};
/**
* A class that implements the semantics of iterators over iterators as
* discussed in the design sections of the IteratorRange class.
*/
template <typename Iterator>
class IteratorOverIterators
{
public:
/**
* Typedef the elements of the collection to give them a name that is more
* distinct.
*/
using BaseIterator = Iterator;
/**
* Constructor. Initialize this iterator-over-iterator in such a way that
* it points to the given argument.
*
* @param iterator An iterator to which this object is supposed to point.
*/
explicit IteratorOverIterators(const BaseIterator &iterator);
/**
* Dereferencing operator.
* @return The iterator within the collection currently pointed to.
*/
const BaseIterator &
operator*() const;
/**
* Dereferencing operator.
* @return The iterator within the collection currently pointed to.
*/
const BaseIterator *
operator->() const;
/**
* Prefix increment operator. Move the current iterator to the next
* element of the collection and return the new value.
*/
IteratorOverIterators &
operator++();
/**
* Postfix increment operator. Move the current iterator to the next
* element of the collection, but return the previous value of the
* iterator.
*/
IteratorOverIterators
operator++(int);
/**
* Comparison operator
* @param i_o_i Another iterator over iterators.
* @return Returns whether the current iterator points to a different
* object than the iterator represented by the argument.
*/
bool
operator!=(const IteratorOverIterators &i_o_i) const;
/**
* Implicit conversion operator.
*
* @warning When you call this conversion operator (i.e., you convert this
* iterator-over-iterators to the iterator we are currently pointing to),
* you obtain a `const` reference to this underlying iterator. The only
* thing you can really do with this result is dereferencing itself: it
* presumably points to something useful, but since you don't know where
* the pointed to object lives, you shouldn't increment or decrement the
* iterator you get from this operator. As a consequence, the returned
* iterator is marked as `const`, as this should prevent you from doing
* anything other than dereference it.
*/
operator const BaseIterator &() const;
/**
* Mark the class as forward iterator and declare some alias which are
* standard for iterators and are used by algorithms to enquire about the
* specifics of the iterators they work on.
*/
using iterator_category = std::forward_iterator_tag;
using value_type = Iterator;
using difference_type = typename Iterator::difference_type;
using pointer = Iterator *;
using reference = Iterator &;
private:
/**
* The object this iterator currently points to.
*/
BaseIterator element_of_iterator_collection;
};
/**
* Create an object of type IteratorRange given the beginning and
* end iterator.
*/
template <typename BaseIterator>
IteratorRange<BaseIterator>
make_iterator_range(const BaseIterator & begin,
const typename identity<BaseIterator>::type &end)
{
IteratorRange<BaseIterator> ir(begin, end);
return ir;
}
// ------------------- template member functions
template <typename Iterator>
inline IteratorOverIterators<Iterator>::IteratorOverIterators(
const BaseIterator &iterator)
: element_of_iterator_collection(iterator)
{}
template <typename Iterator>
inline const typename IteratorOverIterators<Iterator>::BaseIterator &
IteratorOverIterators<Iterator>::operator*() const
{
return element_of_iterator_collection;
}
template <typename Iterator>
inline const typename IteratorOverIterators<Iterator>::BaseIterator *
IteratorOverIterators<Iterator>::operator->() const
{
return &element_of_iterator_collection;
}
template <typename Iterator>
inline IteratorOverIterators<Iterator> &
IteratorOverIterators<Iterator>::operator++()
{
++element_of_iterator_collection;
return *this;
}
template <typename Iterator>
inline IteratorOverIterators<Iterator>
IteratorOverIterators<Iterator>::operator++(int)
{
const IteratorOverIterators old_value = *this;
++element_of_iterator_collection;
return *old_value;
}
template <typename Iterator>
inline bool
IteratorOverIterators<Iterator>::operator!=(
const IteratorOverIterators &i_o_i) const
{
return element_of_iterator_collection != i_o_i.element_of_iterator_collection;
}
template <typename Iterator>
inline IteratorOverIterators<Iterator>::operator const BaseIterator &() const
{
return element_of_iterator_collection;
}
template <typename Iterator>
inline IteratorRange<Iterator>::IteratorRange()
: it_begin()
, it_end()
{}
template <typename Iterator>
inline IteratorRange<Iterator>::IteratorRange(const iterator b,
const iterator e)
: it_begin(b)
, it_end(e)
{}
template <typename Iterator>
inline typename IteratorRange<Iterator>::IteratorOverIterators
IteratorRange<Iterator>::begin()
{
return it_begin;
}
template <typename Iterator>
inline typename IteratorRange<Iterator>::IteratorOverIterators
IteratorRange<Iterator>::begin() const
{
return it_begin;
}
template <typename Iterator>
inline typename IteratorRange<Iterator>::IteratorOverIterators
IteratorRange<Iterator>::end()
{
return it_end;
}
template <typename Iterator>
inline typename IteratorRange<Iterator>::IteratorOverIterators
IteratorRange<Iterator>::end() const
{
return it_end;
}
DEAL_II_NAMESPACE_CLOSE
#endif