Debian Codegraph @

include/deal.II/grid/tria_iterator.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 1998 - 2025 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_tria_iterator_h
16 #define dealii_tria_iterator_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/exceptions.h>
22 #include <deal.II/base/point.h>
23 #include <deal.II/base/template_constraints.h>
24
25 #include <deal.II/grid/tria_iterator_base.h>
26
27 #include <iterator>
28 #include <ostream>
29
30 DEAL_II_NAMESPACE_OPEN
31
32 // Forward declarations
33 #ifndef DOXYGEN
34 template <int dim, int spacedim>
35 DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
36 class Triangulation;
37 template <int, int, int>
38 class TriaAccessorBase;
39
40 template <typename>
41 class TriaIterator;
42 template <typename>
43 class TriaActiveIterator;
44 #endif
45
46
47
48 /**
49 * This class implements an iterator, analogous to those used in the standard
50 * library. It fulfills the requirements of a bidirectional iterator. See the
51 * C++ documentation for further details of iterator specification and usage.
52 *
53 *
54 * In addition to the standard interface, an iterator of this class provides a
55 * <tt>-@></tt> operator, i.e. you can write statements like
56 * @code
57 * cell->set_refine_flag ();
58 * @endcode
59 *
60 * Iterators are used whenever a loop over all lines, quads, cells etc. is to
61 * be performed. These loops can then be coded like this:
62 * @code
63 * cell_iterator cell = tria.begin();
64 * cell_iterator end = tria.end();
65 * for (; cell!=end; ++cell)
66 * if (cell->at_boundary())
67 * cell->set_refine_flag();
68 * @endcode
69 *
70 * Note the usage of <tt>++cell</tt> instead of <tt>cell++</tt> since this does
71 * not involve temporaries and copying. It is recommended to use a fixed value
72 * <tt>end</tt> inside the loop instead of <tt>tria.end()</tt>, since the
73 * creation and copying of these iterators is rather expensive compared to
74 * normal pointers.
75 *
76 * The objects pointed to are accessors, derived from TriaAccessorBase. Which
77 * kind of accessor is determined by the template argument <em>Accessor</em>.
78 * These accessors are not so much data structures as they are a collection of
79 * functions providing access to the data stored in Triangulation or
80 * DoFHandler objects. Using these accessors, the structure of these classes
81 * is hidden from the application program.
82 *
83 * <h3>Which iterator to use when</h3>
84 *
85 * @attention Application programs will rarely use TriaRawIterator, but rather
86 * one of the derived classes TriaIterator or TriaActiveIterator.
87 *
88 * <ul>
89 * <li> TriaRawIterator objects point to lines, cells, etc in the lists
90 * whether they are used or not (in the vectors, also <i>dead</i> objects are
91 * stored, since deletion in vectors is expensive and we also do not want to
92 * destroy the ordering induced by the numbering in the vectors). Therefore
93 * not all raw iterators point to valid objects.
94 *
95 * <li> The derived class TriaIterator selects the valid cells, that is, cells
96 * used somewhere in the triangulation hierarchy.
97 *
98 * <li> TriaActiveIterator objects which only loop over active cells.
99 * </ul>
100 *
101 * <h3>Purpose</h3>
102 *
103 * Iterators are not much slower than operating directly on the data
104 * structures, since they perform the loops that you had to handcode yourself
105 * anyway. Most iterator and accessor functions are inlined.
106 *
107 * The main functionality of iterators, resides in the <tt>++</tt> and
108 * <tt>\--</tt> operators. These move the iterator forward or backward just as
109 * if it were a pointer into an array. Here, this operation is not so easy,
110 * since it may include skipping some elements and the transition between the
111 * triangulation levels. This is completely hidden from the user, though you
112 * can still create an iterator pointing to an arbitrary element. Actually,
113 * the operation of moving iterators back and forth is not done in the
114 * iterator classes, but rather in the accessor classes. Since these are
115 * passed as template arguments, you can write your own versions here to add
116 * more functionality.
117 *
118 * Furthermore, the iterators described here satisfy the requirement of input
119 * and bidirectional iterators as stated by the C++ standard. It is therefore
120 * possible to use the functions from the algorithm section of the C++
121 * standard, e.g., <em>count_if</em> (see the documentation for Triangulation
122 * for an example) and several others.
123 *
124 * <h3>Implementation</h3>
125 *
126 * The iterator class itself does not have much functionality. It only becomes
127 * useful when assigned an Accessor (the second template parameter), which
128 * really does the access to data. An Accessor has to fulfill some
129 * requirements:
130 *
131 * <ul>
132 * <li> It must have two members named <tt>present_level</tt> and
133 * <tt>present_index</tt> storing the address of the element in the
134 * triangulation presently pointed to. These data have to be accessible by all
135 * triangulation iterators listed above.
136 *
137 * <li> It must have a constructor which takes a Triangulation* and two
138 * unsigned integers, denoting the initial level and index, as well as a data
139 * object depending on its type.
140 *
141 * <li> For the TriaIterator and the TriaActiveIterator class, it must have a
142 * member function <tt>bool used()</tt>, for the latter a member function
143 * <tt>bool active()</tt>.
144 *
145 * <li> It must have void operators <tt>++</tt> and <tt>\--</tt>.
146 *
147 * <li> It must declare a local alias <tt>AccessorData</tt> which states the
148 * data type the accessor expects to get passed as fourth constructor
149 * argument. By declaring a local data type, the respective iterator class may
150 * type-safely enforce that data type to be one of its own constructor
151 * argument types. If an accessor class does not need additional data, this
152 * type shall be <tt>void</tt>.
153 * </ul>
154 *
155 * Then the iterator is able to do what it is supposed to. All of the
156 * necessary functions are implemented in the <tt>Accessor</tt> base class,
157 * but you may write your own version (non-virtual, since we use templates) to
158 * add functionality.
159 *
160 * The accessors provided by the library consist of two groups, determined by
161 * whether they access the data of Triangulation objects or DoFHandler objects.
162 * They are derived from TriaAccessor and DoFAccessor, respectively. Each group
163 * also has specialized accessors for cells (as opposed to faces and lines) that
164 * offer more functionality such as accessing neighbors.
165 *
166 * @attention It seems impossible to preserve constness of a triangulation
167 * through iterator usage. Thus, if you declare pointers to a <tt>const</tt>
168 * triangulation object, you should be well aware that you might involuntarily
169 * alter the data stored in the triangulation.
170 *
171 * @note More information on valid and invalid iterators can be found in the
172 * documentation of TriaAccessorBase, where the iterator states are checked
173 * and implemented.
174 *
175 *
176 * <h3>Past-the-end iterators</h3>
177 *
178 * There is a representation of past-the-end-pointers, denoted by special
179 * values of the member variables @p present_level and @p present_index: If
180 * <tt>present_level>=0</tt> and <tt>present_index>=0</tt>, then the object is
181 * valid (there is no check whether the triangulation really has that many
182 * levels or that many cells on the present level when we investigate the
183 * state of an iterator; however, in many places where an iterator is
184 * dereferenced we make this check); if <tt>present_level==-1</tt> and
185 * <tt>present_index==-1</tt>, then the iterator points past the end; in all
186 * other cases, the iterator is considered invalid. You can check this by
187 * calling the <tt>state()</tt> function.
188 *
189 * An iterator is also invalid, if the pointer pointing to the Triangulation
190 * object is invalid or zero.
191 *
192 * Finally, an iterator is invalid, if the element pointed to by @p
193 * present_level and @p present_index is not used, i.e. if the @p used flag is
194 * set to false.
195 *
196 * The last two checks are not made in <tt>state()</tt> since both cases
197 * should only occur upon uninitialized construction through @p memcpy and the
198 * like (the parent triangulation can only be set upon construction). If an
199 * iterator is constructed empty through the empty constructor,
200 * <tt>present_level==-2</tt> and <tt>present_index==-2</tt>. Thus, the
201 * iterator is invalid anyway, regardless of the state of the triangulation
202 * pointer and the state of the element pointed to.
203 *
204 * Past-the-end iterators may also be used to compare an iterator with the
205 * <i>before-the-start</i> value, when running backwards. There is no
206 * distinction between the iterators pointing past the two ends of a vector.
207 *
208 * By defining only one value to be past-the-end and making all other values
209 * invalid provides a second track of security: if we should have forgotten a
210 * check in the library when an iterator is incremented or decremented, we
211 * automatically convert the iterator from the allowed state "past-the-end" to
212 * the disallowed state "invalid" which increases the chance that some time
213 * earlier than for past-the-end iterators an exception is raised.
214 *
215 * @ref Triangulation
216 * @ingroup grid
217 * @ingroup Iterators
218 */
219 template <typename Accessor>
220 class TriaRawIterator
221 {
222 public:
223 /**
224 * Declare the type of the Accessor for use in the outside world. This way
225 * other functions can use the Accessor's type without knowledge of how the
226 * exact implementation actually is.
227 */
228 using AccessorType = Accessor;
229
230 /**
231 * Default constructor. This constructor creates an iterator pointing
232 * to an invalid object. The iterator is consequently not usable.
233 */
234 TriaRawIterator();
235
236 /**
237 * Copy constructor.
238 */
239 TriaRawIterator(const TriaRawIterator &);
240
241 /**
242 * Construct an iterator from the given accessor; the given accessor needs
243 * not be of the same type as the accessor of this class is, but it needs to
244 * be convertible.
245 *
246 * Through this constructor, it is also possible to construct objects for
247 * derived iterators:
248 * @code
249 * DoFCellAccessor dof_accessor;
250 * Triangulation::active_cell_iterator cell = dof_accessor;
251 * @endcode
252 */
253 explicit TriaRawIterator(const Accessor &a);
254
255 /**
256 * Constructor. Assumes that the other accessor type is convertible to the
257 * current one.
258 */
259 template <typename OtherAccessor>
260 explicit TriaRawIterator(const OtherAccessor &a);
261
262 /**
263 * Proper constructor, initialized with the triangulation, the level and
264 * index of the object pointed to. The last parameter is of a type declared
265 * by the accessor class.
266 */
267 TriaRawIterator(
268 const Triangulation<Accessor::dimension, Accessor::space_dimension> *parent,
269 const int level,
270 const int index,
271 const typename AccessorType::AccessorData *local_data = nullptr);
272
273 /**
274 * This is a conversion operator (constructor) which takes another iterator
275 * type and copies the data; this conversion works, if there is a conversion
276 * path from the @p OtherAccessor class to the @p Accessor class of this
277 * object. One such path would be derived class to base class, which for
278 * example may be used to get a Triangulation::raw_cell_iterator from a
279 * DoFHandler::raw_cell_iterator, since the DoFAccessor class is derived
280 * from the TriaAccessorBase class.
281 */
282 template <typename OtherAccessor>
283 TriaRawIterator(const TriaRawIterator<OtherAccessor> &i);
284
285 /**
286 * Another conversion operator, where we use the pointers to the
287 * Triangulation from a TriaAccessorBase object, while the additional data
288 * is used according to the actual type of Accessor.
289 */
290 TriaRawIterator(
291 const TriaAccessorBase<Accessor::structure_dimension,
292 Accessor::dimension,
293 Accessor::space_dimension> &tria_accessor,
294 const typename Accessor::AccessorData *local_data);
295
296 /**
297 * Conversion constructor. Same as above with the difference that it
298 * converts from TriaIterator classes (not TriaRawIterator).
299 */
300 template <typename OtherAccessor>
301 TriaRawIterator(const TriaIterator<OtherAccessor> &i);
302
303 /**
304 * Conversion constructor. Same as above with the difference that it
305 * converts from TriaActiveIterator classes (not TriaRawIterator).
306 */
307 template <typename OtherAccessor>
308 TriaRawIterator(const TriaActiveIterator<OtherAccessor> &i);
309
310 /**
311 * @name Dereferencing
312 */
313 /** @{ */
314 /**
315 * Dereferencing operator, returns a copy of the underlying accessor for
316 * the cell pointed to by the iterator. Usage is thus like
317 * <tt>(*i).index();</tt>
318 *
319 * This function has to be specialized explicitly for the different @p
320 * Pointers, to allow an
321 * <tt>iterator<1,TriangulationLevel<1>::LinesData></tt> to point to
322 * <tt>tria->lines.cells[index]</tt> while for one dimension higher it has
323 * to point to <tt>tria->quads.cells[index]</tt>.
324 *
325 * You must not dereference invalid or past the end iterators.
326 */
327 Accessor
328 operator*() const;
329
330 /**
331 * Dereferencing operator, returns a reference of the internal accessor
332 * for the cell pointed to by the iterator. Usage is thus like
333 * <tt>i->index();</tt>
334 *
335 * There is a @p const and a non-@p const version.
336 */
337 const Accessor *
338 operator->() const;
339
340 /**
341 * Dereferencing operator, non-@p const version.
342 */
343 Accessor *
344 operator->();
345
346
347 /**
348 * In order be able to assign end-iterators for different accessors to each
349 * other, we need an access function which returns the accessor regardless
350 * of its state.
351 *
352 * @warning This function should not be used in application programs. It is
353 * only intended for limited purposes inside the library and it makes
354 * debugging much harder.
355 */
356 const Accessor &
357 access_any() const;
358
359 /** @} */
360
361 /**
362 * Assignment operator.
363 */
364 TriaRawIterator &
365 operator=(const TriaRawIterator &);
366
367 /**
368 * Compare for equality.
369 */
370 template <typename OtherAccessor = Accessor>
371 std::enable_if_t<std::is_convertible_v<OtherAccessor, Accessor>, bool>
372 operator==(const TriaRawIterator<OtherAccessor> &) const;
373
374 /**
375 * Compare for inequality.
376 */
377 bool
378 operator!=(const TriaRawIterator &) const;
379
380 /**
381 * Ordering relation for iterators.
382 *
383 * This relation attempts a total ordering of cells.
384 *
385 * The relation is defined as follows:
386 *
387 * For objects of <tt>Accessor::structure_dimension <
388 * Accessor::dimension</tt>, we simply compare the index of such an object.
389 * The ordering is lexicographic according to the following hierarchy (in
390 * the sense, that the next test is only applied if the previous was
391 * inconclusive):
392 *
393 * <ol>
394 * <li> The past-the-end iterator is always ordered last. Two past-the-end
395 * iterators rank the same, thus false is returned in that case.</li>
396 *
397 * <li> The level of the cell.</li>
398 * <li> The index of a cell inside the level.</li>
399 * </ol>
400 *
401 * @note The ordering is not consistent between different processor in a
402 * parallel::distributed::Triangulation because we rely on index(), which is
403 * likely not the same.
404 */
405 bool
406 operator<(const TriaRawIterator &) const;
407
408 /**
409 * Another comparison operator, implementing with the same ordering as
410 * #operator<.
411 */
412 bool
413 operator>(const TriaRawIterator &) const;
414
415 /**
416 * @name Advancement of iterators
417 */
418 /** @{ */
419 /**
420 * Prefix <tt>++</tt> operator: <tt>++iterator</tt>. This operator advances
421 * the iterator to the next element and returns a reference to
422 * <tt>*this</tt>.
423 */
424 TriaRawIterator &
425 operator++();
426
427 /**
428 * Postfix <tt>++</tt> operator: <tt>iterator++</tt>. This operator advances
429 * the iterator to the next element, but returns an iterator to the element
430 * previously pointed to.
431 *
432 * Since this operation involves a temporary and a copy operation and since
433 * an @p iterator is quite a large object for a pointer, use the prefix
434 * operator <tt>++iterator</tt> whenever possible, especially in the header
435 * of for loops (<tt>for (; iterator!=end; ++iterator)</tt>) since there you
436 * normally never need the returned value.
437 */
438 TriaRawIterator
439 operator++(int);
440
441 /**
442 * Prefix @p \-- operator: @p \--iterator. This operator moves the iterator to
443 * the previous element and returns a reference to <tt>*this</tt>.
444 */
445 TriaRawIterator &
446 operator--();
447
448 /**
449 * Postfix @p \-- operator: @p iterator\--. This operator moves the iterator
450 * to the previous element, but returns an iterator to the element
451 * previously pointed to.
452 *
453 * The same applies as for the postfix operator++: If possible, avoid it by
454 * using the prefix operator form to avoid the use of a temporary variable.
455 */
456 TriaRawIterator
457 operator--(int);
458 /** @} */
459
460 /**
461 * Return the state of the iterator.
462 */
463 IteratorState::IteratorStates
464 state() const;
465
466 /**
467 * Print the iterator to a stream <code>out</code>. The format is
468 * <tt>level.index</tt>.
469 */
470 template <typename StreamType>
471 void
472 print(StreamType &out) const;
473
474
475 /**
476 * Determine an estimate for the memory consumption (in bytes) of this
477 * object.
478 */
479 std::size_t
480 memory_consumption() const;
481
482 /**
483 * Mark the class as bidirectional iterator and declare some alias which
484 * are standard for iterators and are used by algorithms to enquire about the
485 * specifics of the iterators they work on.
486 */
487 using iterator_category = std::bidirectional_iterator_tag;
488 using value_type = Accessor;
489 using difference_type = int;
490 using pointer = Accessor *;
491 using reference = Accessor &;
492
493 /**
494 * @name Exceptions
495 */
496 /** @{ */
497 /**
498 * Exception for TriaObjects with level, i.e. cells.
499 */
500 DeclException1(ExcDereferenceInvalidCell,
501 Accessor,
502 << "You tried to dereference a cell iterator for which this "
503 << "is not possible. More information on this iterator: "
504 << "level=" << arg1.level() << ", index=" << arg1.index()
505 << ", state="
506 << (arg1.state() == IteratorState::valid ?
507 "valid" :
508 (arg1.state() == IteratorState::past_the_end ?
509 "past_the_end" :
510 "invalid")));
511
512 /**
513 * Exception.
514 */
515 DeclException1(ExcDereferenceInvalidObject,
516 Accessor,
517 << "You tried to dereference an iterator for which this "
518 << "is not possible. More information on this iterator: "
519 << "index=" << arg1.index() << ", state="
520 << (arg1.state() == IteratorState::valid ?
521 "valid" :
522 (arg1.state() == IteratorState::past_the_end ?
523 "past_the_end" :
524 "invalid")));
525
526 /**
527 * Exception
528 */
529 DeclException0(ExcAdvanceInvalidObject);
530 /**
531 * Exception
532 */
533 DeclException0(ExcInvalidComparison);
534
535 /** @} */
536 protected:
537 /**
538 * Object holding the real data.
539 */
540 Accessor accessor;
541
542
543 // Make all other iterator class templates friends of this class. This is
544 // necessary for the implementation of conversion constructors.
545 //
546 // In fact, we would not need them to be friends if they were for different
547 // dimensions, but the compiler dislikes giving a fixed dimension and
548 // variable accessor since then it says that would be a partial
549 // specialization.
550 template <typename SomeAccessor>
551 friend class TriaRawIterator;
552 template <typename SomeAccessor>
553 friend class TriaIterator;
554 template <typename SomeAccessor>
555 friend class TriaActiveIterator;
556 };
557
558
559 /**
560 * This specialization of TriaRawIterator provides access only to the
561 * <em>used</em> lines, quads, cells, etc.
562 *
563 * @ingroup grid
564 * @ingroup Iterators
565 */
566 template <typename Accessor>
567 class TriaIterator : public TriaRawIterator<Accessor>
568 {
569 public:
570 /**
571 * Default constructor. This constructor creates an iterator pointing
572 * to an invalid object. The iterator is consequently not usable.
573 */
574 TriaIterator();
575
576 /**
577 * Copy constructor.
578 */
579 TriaIterator(const TriaIterator<Accessor> &);
580
581 /**
582 * Conversion constructor from iterators potentially pointing to non-active
583 * objects (i.e., for objects for which we can't tell that the object is
584 * used just by looking at its type).
585 *
586 * @pre The argument passed to this constructor must either be
587 * (i) a past-the-end iterator; or (ii) it must point to
588 * a used object. All other cases will result in an exception.
589 */
590 TriaIterator(const TriaRawIterator<Accessor> &);
591
592 /**
593 * Constructor, initialized with the triangulation, the level and
594 * index of the object pointed to. The last parameter is of a type declared
595 * by the accessor class.
596 *
597 * @pre The argument passed to this constructor must either be
598 * (i) a past-the-end iterator; or (ii) it must point to
599 * a used object. All other cases will result in an exception.
600 */
601 TriaIterator(
602 const Triangulation<Accessor::dimension, Accessor::space_dimension> *parent,
603 const int level,
604 const int index,
605 const typename Accessor::AccessorData *local_data = nullptr);
606
607 /**
608 * Construct from an accessor of type OtherAccessor that is convertible to
609 * the type Accessor.
610 */
611 template <typename OtherAccessor>
612 explicit TriaIterator(const OtherAccessor &a);
613
614 /**
615 * This is a conversion operator (constructor) which takes another iterator
616 * type and copies the data; this conversion works, if there is a conversion
617 * path from the @p OtherAccessor class to the @p Accessor class of this
618 * object. One such path would be derived class to base class, which for
619 * example may be used to get a Triangulation::cell_iterator from a
620 * DoFHandler::cell_iterator, since the DoFAccessor class is derived from
621 * the TriaAccessorBase class.
622 */
623 template <typename OtherAccessor>
624 TriaIterator(const TriaIterator<OtherAccessor> &i);
625
626 /**
627 * Another conversion operator, where we use the pointers to the
628 * Triangulation from a TriaAccessorBase object, while the additional data
629 * is used according to the actual type of Accessor.
630 */
631 TriaIterator(const TriaAccessorBase<Accessor::structure_dimension,
632 Accessor::dimension,
633 Accessor::space_dimension> &tria_accessor,
634 const typename Accessor::AccessorData *local_data);
635
636 /**
637 * Similar conversion operator to the above one, but does a check whether
638 * the iterator points to a used element, which is necessary for raw
639 * iterators.
640 */
641 template <typename OtherAccessor>
642 TriaIterator(const TriaRawIterator<OtherAccessor> &i);
643
644 /**
645 * Similar conversion operator to the above one, but for conversion from
646 * active iterators.
647 */
648 template <typename OtherAccessor>
649 TriaIterator(const TriaActiveIterator<OtherAccessor> &i);
650
651 /**
652 * Assignment operator.
653 */
654 TriaIterator<Accessor> &
655 operator=(const TriaIterator<Accessor> &);
656
657 /**
658 * Cross assignment operator. This assignment is only valid if the given
659 * iterator points to a used element.
660 */
661 TriaIterator<Accessor> &
662 operator=(const TriaRawIterator<Accessor> &);
663
664 /**
665 * Assignment operator. Requires, that Accessor can be copied from
666 * OtherAccessor.
667 */
668 template <class OtherAccessor>
669 TriaIterator<Accessor> &
670 operator=(const TriaIterator<OtherAccessor> &);
671
672 /**
673 * Cross assignment operator. This assignment is only valid if the given
674 * iterator points to a used element. Requires, that Accessor can be copied
675 * from OtherAccessor.
676 */
677 template <class OtherAccessor>
678 TriaIterator<Accessor> &
679 operator=(const TriaRawIterator<OtherAccessor> &);
680
681 /**
682 * @name Advancement of iterators
683 */
684 /** @{ */
685 /**
686 * Prefix <tt>++</tt> operator: <tt>++i</tt>. This operator advances the
687 * iterator to the next used element and returns a reference to
688 * <tt>*this</tt>.
689 */
690 TriaIterator<Accessor> &
691 operator++();
692
693 /**
694 * Postfix <tt>++</tt> operator: <tt>i++</tt>. This operator advances the
695 * iterator to the next used element, but returns an iterator to the element
696 * previously pointed to. Since this involves a temporary and a copy
697 * operation and since an @p active_iterator is quite a large object for a
698 * pointer, use the prefix operator <tt>++i</tt> whenever possible,
699 * especially in the head of for loops (<tt>for (; i!=end; ++i)</tt>) since
700 * there you normally never need the returned value.
701 */
702 TriaIterator<Accessor>
703 operator++(int);
704
705 /**
706 * Prefix @p \-- operator: @p \--i. This operator advances the iterator to the
707 * previous used element and returns a reference to <tt>*this</tt>.
708 */
709 TriaIterator<Accessor> &
710 operator--();
711
712 /**
713 * Postfix @p \-- operator: @p i\--.
714 */
715 TriaIterator<Accessor>
716 operator--(int);
717 /** @} */
718
719 /**
720 * Declare some aliases which are standard for iterators and are used
721 * by algorithms to enquire about the specifics of the iterators they
722 * work on.
723 */
724 using iterator_category =
725 typename TriaRawIterator<Accessor>::iterator_category;
726 using value_type = typename TriaRawIterator<Accessor>::value_type;
727 using pointer = typename TriaRawIterator<Accessor>::pointer;
728 using reference = typename TriaRawIterator<Accessor>::reference;
729 using difference_type = typename TriaRawIterator<Accessor>::difference_type;
730
731 /**
732 * Exception
733 */
734 DeclException0(ExcAssignmentOfUnusedObject);
735 };
736
737
738 /**
739 * This specialization of TriaIterator provides access only to the
740 * <em>active</em> lines, quads, cells, etc. An active cell is a cell which is
741 * not refined and thus a cell on which calculations on the finest level are
742 * done.
743 *
744 * @ingroup grid
745 * @ingroup Iterators
746 */
747 template <typename Accessor>
748 class TriaActiveIterator : public TriaIterator<Accessor>
749 {
750 public:
751 /**
752 * Default constructor. This constructor creates an iterator pointing
753 * to an invalid object. The iterator is consequently not usable.
754 */
755 TriaActiveIterator();
756
757 /**
758 * Copy constructor.
759 */
760 TriaActiveIterator(const TriaActiveIterator<Accessor> &);
761
762 /**
763 * Conversion constructor creating an active iterator from an iterators
764 * pointing to a potentially non-active object (or at least from which
765 * it is not apparent from the type alone that it is active).
766 *
767 * @pre The argument passed to this constructor must either be
768 * (i) a past-the-end iterator; or (ii) it must point to
769 * an active object. All other cases will result in an exception.
770 */
771 TriaActiveIterator(const TriaRawIterator<Accessor> &);
772
773 /**
774 * Conversion constructor creating an active iterator from an iterators
775 * pointing to a potentially non-active object (or at least from which
776 * it is not apparent from the type alone that it is active).
777 *
778 * @pre The argument passed to this constructor must either be
779 * (i) a past-the-end iterator; or (ii) it must point to
780 * an active object. All other cases will result in an exception.
781 */
782 TriaActiveIterator(const TriaIterator<Accessor> &);
783
784 /**
785 * Constructor, initialized with the triangulation, the level and
786 * index of the object pointed to. The last parameter is of a type declared
787 * by the accessor class used by the current iterator.
788 *
789 * @pre The argument passed to this constructor must either be
790 * (i) a past-the-end iterator; or (ii) it must point to
791 * an active object. All other cases will result in an exception.
792 */
793 TriaActiveIterator(
794 const Triangulation<Accessor::dimension, Accessor::space_dimension> *parent,
795 const int level,
796 const int index,
797 const typename Accessor::AccessorData *local_data = nullptr);
798
799 /**
800 * This is a conversion operator (constructor) which takes another iterator
801 * type and copies the data; this conversion works, if there is a conversion
802 * path from the @p OtherAccessor class to the @p Accessor class of this
803 * object. One such path would be derived class to base class, which for
804 * example may be used to get a Triangulation::active_cell_iterator from a
805 * DoFHandler::active_cell_iterator, since the DoFAccessor class is derived
806 * from the TriaAccessorBase class.
807 */
808 template <typename OtherAccessor>
809 TriaActiveIterator(const TriaActiveIterator<OtherAccessor> &i);
810
811 /**
812 * Another conversion operator, where we use the pointers to the
813 * Triangulation from a TriaAccessorBase object, while the additional data
814 * is used according to the actual type of Accessor.
815 */
816 TriaActiveIterator(
817 const TriaAccessorBase<Accessor::structure_dimension,
818 Accessor::dimension,
819 Accessor::space_dimension> &tria_accessor,
820 const typename Accessor::AccessorData *local_data);
821
822 /**
823 * Similar conversion operator to the above one, but does a check whether
824 * the iterator points to a used element, and is active, which is necessary
825 * for raw iterators. Since usual iterators are also raw iterators, this
826 * constructor works also for parameters of type
827 * <tt>TriaIterator<OtherAccessor></tt>.
828 *
829 * @pre The argument passed to this constructor must either be
830 * (i) a past-the-end iterator; or (ii) it must point to
831 * an active object. All other cases will result in an exception.
832 */
833 template <typename OtherAccessor>
834 TriaActiveIterator(const TriaRawIterator<OtherAccessor> &i);
835
836 /**
837 * Assignment operator.
838 */
839 TriaActiveIterator<Accessor> &
840 operator=(const TriaActiveIterator<Accessor> &);
841
842 /**
843 * Cross assignment operator. This assignment is only valid if the given
844 * iterator points to an active element.
845 */
846 TriaActiveIterator<Accessor> &
847 operator=(const TriaIterator<Accessor> &);
848
849 /**
850 * Cross assignment operator. This assignment is only valid if the given
851 * iterator points to an active element or past the end.
852 */
853 TriaActiveIterator<Accessor> &
854 operator=(const TriaRawIterator<Accessor> &);
855
856 /**
857 * Assignment operator. Requires, that Accessor can be copied from
858 * OtherAccessor.
859 */
860 template <class OtherAccessor>
861 TriaActiveIterator<Accessor> &
862 operator=(const TriaActiveIterator<OtherAccessor> &);
863
864 /**
865 * Cross assignment operator. This assignment is only valid if the given
866 * iterator points to an active element or past the end. Requires, that
867 * Accessor can be copied from OtherAccessor.
868 */
869 template <class OtherAccessor>
870 TriaActiveIterator<Accessor> &
871 operator=(const TriaRawIterator<OtherAccessor> &);
872
873 /**
874 * Cross assignment operator. This assignment is only valid if the given
875 * iterator points to an active element. Requires, that Accessor can be
876 * copied from OtherAccessor.
877 */
878 template <class OtherAccessor>
879 TriaActiveIterator<Accessor> &
880 operator=(const TriaIterator<OtherAccessor> &);
881
882 /**
883 * Prefix <tt>++</tt> operator: <tt>++i</tt>. This operator advances the
884 * iterator to the next active element and returns a reference to
885 * <tt>*this</tt>.
886 */
887 TriaActiveIterator<Accessor> &
888 operator++();
889
890 /**
891 * @name Advancement of iterators
892 */
893 /** @{ */
894 /**
895 * Postfix <tt>++</tt> operator: <tt>i++</tt>. This operator advances the
896 * iterator to the next active element, but returns an iterator to the
897 * element previously pointed to. Since this involves a temporary and a copy
898 * operation and since an @p active_iterator is quite a large object for a
899 * pointer, use the prefix operator <tt>++i</tt> whenever possible,
900 * especially in the head of for loops (<tt>for (; i!=end; ++i)</tt>) since
901 * there you normally never need the returned value.
902 */
903 TriaActiveIterator<Accessor>
904 operator++(int);
905
906 /**
907 * Prefix @p \-- operator: @p \--i. This operator advances the iterator to the
908 * previous active element and returns a reference to <tt>*this</tt>.
909 */
910 TriaActiveIterator<Accessor> &
911 operator--();
912
913 /**
914 * Postfix @p \-- operator: @p i\--.
915 */
916 TriaActiveIterator<Accessor>
917 operator--(int);
918 /** @} */
919
920 /**
921 * Declare some alias which are standard for iterators and are used
922 * by algorithms to enquire about the specifics of the iterators they
923 * work on.
924 */
925 using iterator_category = typename TriaIterator<Accessor>::iterator_category;
926 using value_type = typename TriaIterator<Accessor>::value_type;
927 using pointer = typename TriaIterator<Accessor>::pointer;
928 using reference = typename TriaIterator<Accessor>::reference;
929 using difference_type = typename TriaIterator<Accessor>::difference_type;
930
931 /**
932 * Exception
933 */
934 DeclException0(ExcAssignmentOfInactiveObject);
935 };
936
937
938 /*----------------------- Inline functions -------------------*/
939
940
941 template <typename Accessor>
942 inline TriaRawIterator<Accessor>::TriaRawIterator(const Accessor &a)
943 : accessor(a)
944 {}
945
946
947
948 template <typename Accessor>
949 template <typename OtherAccessor>
950 inline TriaRawIterator<Accessor>::TriaRawIterator(const OtherAccessor &a)
951 : accessor(a)
952 {}
953
954
955
956 template <typename Accessor>
957 template <typename OtherAccessor>
958 inline TriaRawIterator<Accessor>::TriaRawIterator(
959 const TriaRawIterator<OtherAccessor> &i)
960 : accessor(i.accessor)
961 {}
962
963
964
965 template <typename Accessor>
966 template <typename OtherAccessor>
967 inline TriaRawIterator<Accessor>::TriaRawIterator(
968 const TriaIterator<OtherAccessor> &i)
969 : accessor(i.accessor)
970 {}
971
972
973
974 template <typename Accessor>
975 template <typename OtherAccessor>
976 inline TriaRawIterator<Accessor>::TriaRawIterator(
977 const TriaActiveIterator<OtherAccessor> &i)
978 : accessor(i.accessor)
979 {}
980
981
982
983 template <typename Accessor>
984 inline Accessor
985 TriaRawIterator<Accessor>::operator*() const
986 {
987 Assert(Accessor::structure_dimension != Accessor::dimension ||
988 state() == IteratorState::valid,
989 ExcDereferenceInvalidCell(accessor));
990 Assert(Accessor::structure_dimension == Accessor::dimension ||
991 state() == IteratorState::valid,
992 ExcDereferenceInvalidObject(accessor));
993
994 return accessor;
995 }
996
997
998
999 template <typename Accessor>
1000 inline const Accessor &
1001 TriaRawIterator<Accessor>::access_any() const
1002 {
1003 return accessor;
1004 }
1005
1006
1007
1008 template <typename Accessor>
1009 inline const Accessor *
1010 TriaRawIterator<Accessor>::operator->() const
1011 {
1012 return &accessor;
1013 }
1014
1015
1016
1017 template <typename Accessor>
1018 inline Accessor *
1019 TriaRawIterator<Accessor>::operator->()
1020 {
1021 return &accessor;
1022 }
1023
1024
1025
1026 template <typename Accessor>
1027 inline IteratorState::IteratorStates
1028 TriaRawIterator<Accessor>::state() const
1029 {
1030 return accessor.state();
1031 }
1032
1033
1034
1035 template <typename Accessor>
1036 inline bool
1037 TriaRawIterator<Accessor>::operator<(
1038 const TriaRawIterator<Accessor> &other) const
1039 {
1040 Assert(state() != IteratorState::invalid,
1041 ExcDereferenceInvalidObject(accessor));
1042 Assert(other.state() != IteratorState::invalid,
1043 ExcDereferenceInvalidObject(other.accessor));
1044
1045 Assert(&accessor.get_triangulation() == &other.accessor.get_triangulation(),
1046 ExcInvalidComparison());
1047
1048 // Deal with iterators past end
1049 if (state() == IteratorState::past_the_end)
1050 return false;
1051 if (other.state() == IteratorState::past_the_end)
1052 return true;
1053
1054 return ((**this) < (*other));
1055 }
1056
1057
1058
1059 template <typename Accessor>
1060 inline bool
1061 TriaRawIterator<Accessor>::operator>(
1062 const TriaRawIterator<Accessor> &other) const
1063 {
1064 return (other < *this);
1065 }
1066
1067
1068
1069 template <typename Accessor>
1070 inline TriaRawIterator<Accessor> &
1071 TriaRawIterator<Accessor>::operator++()
1072 {
1073 Assert(state() == IteratorState::valid, ExcAdvanceInvalidObject());
1074
1075 ++accessor;
1076 return *this;
1077 }
1078
1079
1080
1081 template <typename Accessor>
1082 inline TriaRawIterator<Accessor> &
1083 TriaRawIterator<Accessor>::operator--()
1084 {
1085 Assert(state() == IteratorState::valid, ExcAdvanceInvalidObject());
1086
1087 --accessor;
1088 return *this;
1089 }
1090
1091
1092
1093 template <typename Accessor>
1094 template <typename StreamType>
1095 inline void
1096 TriaRawIterator<Accessor>::print(StreamType &out) const
1097 {
1098 if (Accessor::structure_dimension == Accessor::dimension)
1099 out << accessor.level() << '.' << accessor.index();
1100 else
1101 out << accessor.index();
1102 }
1103
1104
1105
1106 template <typename Accessor>
1107 inline std::size_t
1108 TriaRawIterator<Accessor>::memory_consumption() const
1109 {
1110 return sizeof(TriaRawIterator<Accessor>);
1111 }
1112
1113
1114
1115 template <typename Accessor>
1116 template <typename OtherAccessor>
1117 inline TriaIterator<Accessor>::TriaIterator(
1118 const TriaIterator<OtherAccessor> &i)
1119 : TriaRawIterator<Accessor>(i.accessor)
1120 {}
1121
1122
1123
1124 template <typename Accessor>
1125 template <typename OtherAccessor>
1126 inline TriaIterator<Accessor>::TriaIterator(
1127 const TriaActiveIterator<OtherAccessor> &i)
1128 : TriaRawIterator<Accessor>(i.accessor)
1129 {}
1130
1131
1132
1133 template <typename Accessor>
1134 template <typename OtherAccessor>
1135 inline TriaIterator<Accessor>::TriaIterator(
1136 const TriaRawIterator<OtherAccessor> &i)
1137 : TriaRawIterator<Accessor>(i.accessor)
1138 {
1139 if constexpr (running_in_debug_mode())
1140 {
1141 // do this like this, because:
1142 // if we write
1143 // "Assert (IteratorState::past_the_end || used)"
1144 // used() is called anyway, even if
1145 // state==IteratorState::past_the_end, and will then
1146 // throw the exception!
1147 if (this->state() != IteratorState::past_the_end)
1148 Assert(this->accessor.used(), ExcAssignmentOfUnusedObject());
1149 }
1150 }
1151
1152 template <typename Accessor>
1153 template <typename OtherAccessor>
1154 TriaIterator<Accessor>::TriaIterator(const OtherAccessor &a)
1155 : TriaRawIterator<Accessor>(a)
1156 {
1157 if constexpr (running_in_debug_mode())
1158 {
1159 // do this like this, because:
1160 // if we write
1161 // "Assert (IteratorState::past_the_end || used)"
1162 // used() is called anyway, even if
1163 // state==IteratorState::past_the_end, and will then
1164 // throw the exception!
1165 if (this->state() != IteratorState::past_the_end)
1166 Assert(this->accessor.used(), ExcAssignmentOfUnusedObject());
1167 }
1168 }
1169
1170 template <typename Accessor>
1171 template <typename OtherAccessor>
1172 inline TriaActiveIterator<Accessor>::TriaActiveIterator(
1173 const TriaActiveIterator<OtherAccessor> &i)
1174 : TriaIterator<Accessor>(i.accessor)
1175 {}
1176
1177
1178
1179 template <typename Accessor>
1180 template <typename OtherAccessor>
1181 inline TriaActiveIterator<Accessor>::TriaActiveIterator(
1182 const TriaRawIterator<OtherAccessor> &i)
1183 : TriaIterator<Accessor>(i)
1184 {
1185 if constexpr (running_in_debug_mode())
1186 {
1187 // do this like this, because:
1188 // if we write
1189 // "Assert (IteratorState::past_the_end || !has_children())"
1190 // has_children() is called anyway, even if
1191 // state==IteratorState::past_the_end, and will then
1192 // throw the exception!
1193 if (this->state() != IteratorState::past_the_end)
1194 Assert(this->accessor.has_children() == false,
1195 ExcAssignmentOfInactiveObject());
1196 }
1197 }
1198
1199
1200
1201 /**
1202 * Print the address to which this iterator points to @p out. The address is
1203 * given by the pair <tt>(level,index)</tt>, where @p index is an index
1204 * relative to the level in which the object is that is pointed to.
1205 */
1206 template <typename Accessor>
1207 inline std::ostream &
1208 operator<<(std::ostream &out, const TriaRawIterator<Accessor> &i)
1209 {
1210 i.print(out);
1211 return out;
1212 }
1213
1214
1215
1216 /**
1217 * Print the address to which this iterator points to @p out. The address is
1218 * given by the pair <tt>(level,index)</tt>, where @p index is an index
1219 * relative to the level in which the object is that is pointed to.
1220 */
1221 template <typename Accessor>
1222 inline std::ostream &
1223 operator<<(std::ostream &out, const TriaIterator<Accessor> &i)
1224 {
1225 i.print(out);
1226 return out;
1227 }
1228
1229
1230
1231 /**
1232 * Print the address to which this iterator points to @p out. The address is
1233 * given by the pair <tt>(level,index)</tt>, where @p index is an index
1234 * relative to the level in which the object is that is pointed to.
1235 */
1236 template <typename Accessor>
1237 inline std::ostream &
1238 operator<<(std::ostream &out, const TriaActiveIterator<Accessor> &i)
1239 {
1240 i.print(out);
1241 return out;
1242 }
1243
1244
1245 #ifndef DOXYGEN
1246
1247 /*------------------------ Functions: TriaRawIterator ------------------*/
1248
1249
1250 template <typename Accessor>
1251 inline TriaRawIterator<Accessor>::TriaRawIterator()
1252 : accessor(nullptr, -2, -2, nullptr)
1253 {}
1254
1255
1256 template <typename Accessor>
1257 inline TriaRawIterator<Accessor>::TriaRawIterator(
1258 const TriaRawIterator<Accessor> &i)
1259 : accessor(i.accessor)
1260 {}
1261
1262
1263
1264 template <typename Accessor>
1265 inline TriaRawIterator<Accessor>::TriaRawIterator(
1266 const Triangulation<Accessor::dimension, Accessor::space_dimension> *parent,
1267 const int level,
1268 const int index,
1269 const typename Accessor::AccessorData *local_data)
1270 : accessor(parent, level, index, local_data)
1271 {}
1272
1273
1274 template <typename Accessor>
1275 inline TriaRawIterator<Accessor>::TriaRawIterator(
1276 const TriaAccessorBase<Accessor::structure_dimension,
1277 Accessor::dimension,
1278 Accessor::space_dimension> &tria_accessor,
1279 const typename Accessor::AccessorData *local_data)
1280 : accessor(nullptr, -2, -2, local_data)
1281 {
1282 accessor.copy_from(tria_accessor);
1283 }
1284
1285
1286 template <typename Accessor>
1287 inline TriaRawIterator<Accessor> &
1288 TriaRawIterator<Accessor>::operator=(const TriaRawIterator<Accessor> &i)
1289 {
1290 accessor.copy_from(i.accessor);
1291
1292 return *this;
1293 }
1294
1295
1296
1297 template <typename Accessor>
1298 template <typename OtherAccessor>
1299 inline std::enable_if_t<std::is_convertible_v<OtherAccessor, Accessor>, bool>
1300 TriaRawIterator<Accessor>::operator==(
1301 const TriaRawIterator<OtherAccessor> &other) const
1302 {
1303 return accessor == other.accessor;
1304 }
1305
1306
1307 template <typename Accessor>
1308 inline bool
1309 TriaRawIterator<Accessor>::operator!=(
1310 const TriaRawIterator<Accessor> &other) const
1311 {
1312 return !(*this == other);
1313 }
1314
1315
1316 template <typename Accessor>
1317 inline TriaRawIterator<Accessor>
1318 TriaRawIterator<Accessor>::operator++(int)
1319 {
1320 TriaRawIterator<Accessor> tmp(*this);
1321 operator++();
1322
1323 return tmp;
1324 }
1325
1326
1327 template <typename Accessor>
1328 inline TriaRawIterator<Accessor>
1329 TriaRawIterator<Accessor>::operator--(int)
1330 {
1331 TriaRawIterator<Accessor> tmp(*this);
1332 operator--();
1333
1334 return tmp;
1335 }
1336
1337
1338 /*----------------------- functions: TriaIterator ---------------*/
1339
1340
1341 template <typename Accessor>
1342 inline TriaIterator<Accessor>::TriaIterator()
1343 : TriaRawIterator<Accessor>()
1344 {}
1345
1346
1347 template <typename Accessor>
1348 inline TriaIterator<Accessor>::TriaIterator(const TriaIterator<Accessor> &i)
1349 : TriaRawIterator<Accessor>(i.accessor)
1350 {}
1351
1352
1353 template <typename Accessor>
1354 inline TriaIterator<Accessor>::TriaIterator(const TriaRawIterator<Accessor> &i)
1355 : TriaRawIterator<Accessor>(i.accessor)
1356 {
1357 if constexpr (running_in_debug_mode())
1358 {
1359 // do this like this, because:
1360 // if we write
1361 // "Assert (IteratorState::past_the_end || used)"
1362 // used() is called anyway, even if
1363 // state==IteratorState::past_the_end, and will then
1364 // throw the exception!
1365 if (this->state() != IteratorState::past_the_end)
1366 Assert(this->accessor.used(), ExcAssignmentOfUnusedObject());
1367 }
1368 }
1369
1370
1371 template <typename Accessor>
1372 inline TriaIterator<Accessor>::TriaIterator(
1373 const Triangulation<Accessor::dimension, Accessor::space_dimension> *parent,
1374 const int level,
1375 const int index,
1376 const typename Accessor::AccessorData *local_data)
1377 : TriaRawIterator<Accessor>(parent, level, index, local_data)
1378 {
1379 if constexpr (running_in_debug_mode())
1380 {
1381 // do this like this, because:
1382 // if we write
1383 // "Assert (IteratorState::past_the_end || used)"
1384 // used() is called anyway, even if
1385 // state==IteratorState::past_the_end, and will then
1386 // throw the exception!
1387 if (this->state() != IteratorState::past_the_end)
1388 Assert(this->accessor.used(), ExcAssignmentOfUnusedObject());
1389 }
1390 }
1391
1392
1393 template <typename Accessor>
1394 inline TriaIterator<Accessor>::TriaIterator(
1395 const TriaAccessorBase<Accessor::structure_dimension,
1396 Accessor::dimension,
1397 Accessor::space_dimension> &tria_accessor,
1398 const typename Accessor::AccessorData *local_data)
1399 : TriaRawIterator<Accessor>(tria_accessor, local_data)
1400 {
1401 if constexpr (running_in_debug_mode())
1402 {
1403 // do this like this, because:
1404 // if we write
1405 // "Assert (IteratorState::past_the_end || used)"
1406 // used() is called anyway, even if
1407 // state==IteratorState::past_the_end, and will then
1408 // throw the exception!
1409 if (this->state() != IteratorState::past_the_end)
1410 Assert(this->accessor.used(), ExcAssignmentOfUnusedObject());
1411 }
1412 }
1413
1414
1415 template <typename Accessor>
1416 inline TriaIterator<Accessor> &
1417 TriaIterator<Accessor>::operator=(const TriaIterator<Accessor> &i)
1418 {
1419 this->accessor.copy_from(i.accessor);
1420 return *this;
1421 }
1422
1423
1424 template <typename Accessor>
1425 template <typename OtherAccessor>
1426 inline TriaIterator<Accessor> &
1427 TriaIterator<Accessor>::operator=(const TriaIterator<OtherAccessor> &i)
1428 {
1429 this->accessor.copy_from(i.accessor);
1430 return *this;
1431 }
1432
1433
1434 template <typename Accessor>
1435 inline TriaIterator<Accessor> &
1436 TriaIterator<Accessor>::operator=(const TriaRawIterator<Accessor> &i)
1437 {
1438 this->accessor.copy_from(i.accessor);
1439 if constexpr (running_in_debug_mode())
1440 {
1441 // do this like this, because:
1442 // if we write
1443 // "Assert (IteratorState::past_the_end || used)"
1444 // used() is called anyway, even if
1445 // state==IteratorState::past_the_end, and will then
1446 // throw the exception!
1447 if (this->state() != IteratorState::past_the_end)
1448 Assert(this->accessor.used(), ExcAssignmentOfUnusedObject());
1449 }
1450 return *this;
1451 }
1452
1453
1454 template <typename Accessor>
1455 template <typename OtherAccessor>
1456 inline TriaIterator<Accessor> &
1457 TriaIterator<Accessor>::operator=(const TriaRawIterator<OtherAccessor> &i)
1458 {
1459 this->accessor.copy_from(i.accessor);
1460 if constexpr (running_in_debug_mode())
1461 {
1462 // do this like this, because:
1463 // if we write
1464 // "Assert (IteratorState::past_the_end || used)"
1465 // used() is called anyway, even if
1466 // state==IteratorState::past_the_end, and will then
1467 // throw the exception!
1468 if (this->state() != IteratorState::past_the_end)
1469 Assert(this->accessor.used(), ExcAssignmentOfUnusedObject());
1470 }
1471 return *this;
1472 }
1473
1474
1475 template <typename Accessor>
1476 inline TriaIterator<Accessor> &
1477 TriaIterator<Accessor>::operator++()
1478 {
1479 while (TriaRawIterator<Accessor>::operator++(),
1480 (this->state() == IteratorState::valid))
1481 if (this->accessor.used() == true)
1482 return *this;
1483 return *this;
1484 }
1485
1486
1487 template <typename Accessor>
1488 inline TriaIterator<Accessor>
1489 TriaIterator<Accessor>::operator++(int)
1490 {
1491 TriaIterator<Accessor> tmp(*this);
1492 operator++();
1493
1494 return tmp;
1495 }
1496
1497
1498 template <typename Accessor>
1499 inline TriaIterator<Accessor> &
1500 TriaIterator<Accessor>::operator--()
1501 {
1502 while (TriaRawIterator<Accessor>::operator--(),
1503 (this->state() == IteratorState::valid))
1504 if (this->accessor.used() == true)
1505 return *this;
1506 return *this;
1507 }
1508
1509
1510 template <typename Accessor>
1511 inline TriaIterator<Accessor>
1512 TriaIterator<Accessor>::operator--(int)
1513 {
1514 TriaIterator<Accessor> tmp(*this);
1515 operator--();
1516
1517 return tmp;
1518 }
1519
1520
1521 /*----------------------- functions: TriaActiveIterator ---------------*/
1522
1523
1524 template <typename Accessor>
1525 inline TriaActiveIterator<Accessor>::TriaActiveIterator()
1526 : TriaIterator<Accessor>()
1527 {}
1528
1529
1530 template <typename Accessor>
1531 inline TriaActiveIterator<Accessor>::TriaActiveIterator(
1532 const TriaActiveIterator<Accessor> &i)
1533 : TriaIterator<Accessor>(static_cast<TriaIterator<Accessor>>(i))
1534 {}
1535
1536
1537 template <typename Accessor>
1538 inline TriaActiveIterator<Accessor>::TriaActiveIterator(
1539 const TriaRawIterator<Accessor> &i)
1540 : TriaIterator<Accessor>(i)
1541 {
1542 if constexpr (running_in_debug_mode())
1543 {
1544 // do this like this, because:
1545 // if we write
1546 // "Assert (IteratorState::past_the_end || !has_children())"
1547 // has_children() is called anyway, even if
1548 // state==IteratorState::past_the_end, and will then
1549 // throw the exception!
1550 if (this->state() != IteratorState::past_the_end)
1551 Assert(this->accessor.has_children() == false,
1552 ExcAssignmentOfInactiveObject());
1553 }
1554 }
1555
1556
1557 template <typename Accessor>
1558 inline TriaActiveIterator<Accessor>::TriaActiveIterator(
1559 const TriaIterator<Accessor> &i)
1560 : TriaIterator<Accessor>(i)
1561 {
1562 if constexpr (running_in_debug_mode())
1563 {
1564 // do this like this, because:
1565 // if we write
1566 // "Assert (IteratorState::past_the_end || !has_children())"
1567 // has_children() is called anyway, even if
1568 // state==IteratorState::past_the_end, and will then
1569 // throw the exception!
1570 if (this->state() != IteratorState::past_the_end)
1571 Assert(this->accessor.has_children() == false,
1572 ExcAssignmentOfInactiveObject());
1573 }
1574 }
1575
1576
1577 template <typename Accessor>
1578 inline TriaActiveIterator<Accessor>::TriaActiveIterator(
1579 const Triangulation<Accessor::dimension, Accessor::space_dimension> *parent,
1580 const int level,
1581 const int index,
1582 const typename Accessor::AccessorData *local_data)
1583 : TriaIterator<Accessor>(parent, level, index, local_data)
1584 {
1585 if constexpr (running_in_debug_mode())
1586 {
1587 // do this like this, because:
1588 // if we write
1589 // "Assert (IteratorState::past_the_end || !has_children())"
1590 // has_children() is called anyway, even if
1591 // state==IteratorState::past_the_end, and will then
1592 // throw the exception!
1593 if (this->state() != IteratorState::past_the_end)
1594 Assert(this->accessor.has_children() == false,
1595 ExcAssignmentOfInactiveObject());
1596 }
1597 }
1598
1599
1600 template <typename Accessor>
1601 inline TriaActiveIterator<Accessor>::TriaActiveIterator(
1602 const TriaAccessorBase<Accessor::structure_dimension,
1603 Accessor::dimension,
1604 Accessor::space_dimension> &tria_accessor,
1605 const typename Accessor::AccessorData *local_data)
1606 : TriaIterator<Accessor>(tria_accessor, local_data)
1607 {
1608 if constexpr (running_in_debug_mode())
1609 {
1610 // do this like this, because:
1611 // if we write
1612 // "Assert (IteratorState::past_the_end || !has_children())"
1613 // has_children() is called anyway, even if
1614 // state==IteratorState::past_the_end, and will then
1615 // throw the exception!
1616 if (this->state() != IteratorState::past_the_end)
1617 Assert(this->accessor.has_children() == false,
1618 ExcAssignmentOfInactiveObject());
1619 }
1620 }
1621
1622
1623 template <typename Accessor>
1624 inline TriaActiveIterator<Accessor> &
1625 TriaActiveIterator<Accessor>::operator=(const TriaActiveIterator<Accessor> &i)
1626 {
1627 this->accessor.copy_from(i.accessor);
1628 return *this;
1629 }
1630
1631
1632 template <typename Accessor>
1633 template <class OtherAccessor>
1634 inline TriaActiveIterator<Accessor> &
1635 TriaActiveIterator<Accessor>::operator=(
1636 const TriaActiveIterator<OtherAccessor> &i)
1637 {
1638 this->accessor.copy_from(i.accessor);
1639 return *this;
1640 }
1641
1642
1643 template <typename Accessor>
1644 inline TriaActiveIterator<Accessor> &
1645 TriaActiveIterator<Accessor>::operator=(const TriaRawIterator<Accessor> &i)
1646 {
1647 this->accessor.copy_from(i.accessor);
1648 if constexpr (running_in_debug_mode())
1649 {
1650 // do this like this, because:
1651 // if we write
1652 // "Assert (IteratorState::past_the_end || !has_children())"
1653 // has_children() is called anyway, even if
1654 // state==IteratorState::past_the_end, and will then
1655 // throw the exception!
1656 if (this->state() != IteratorState::past_the_end)
1657 Assert(this->accessor.used() && this->accessor.has_children() == false,
1658 ExcAssignmentOfInactiveObject());
1659 }
1660 return *this;
1661 }
1662
1663
1664 template <typename Accessor>
1665 template <class OtherAccessor>
1666 inline TriaActiveIterator<Accessor> &
1667 TriaActiveIterator<Accessor>::operator=(const TriaRawIterator<OtherAccessor> &i)
1668 {
1669 this->accessor.copy_from(i.accessor);
1670 if constexpr (running_in_debug_mode())
1671 {
1672 // do this like this, because:
1673 // if we write
1674 // "Assert (IteratorState::past_the_end || !has_children())"
1675 // has_children() is called anyway, even if
1676 // state==IteratorState::past_the_end, and will then
1677 // throw the exception!
1678 if (this->state() != IteratorState::past_the_end)
1679 Assert(this->accessor.used() && this->accessor.has_children() == false,
1680 ExcAssignmentOfInactiveObject());
1681 }
1682 return *this;
1683 }
1684
1685
1686 template <typename Accessor>
1687 template <class OtherAccessor>
1688 inline TriaActiveIterator<Accessor> &
1689 TriaActiveIterator<Accessor>::operator=(const TriaIterator<OtherAccessor> &i)
1690 {
1691 this->accessor.copy_from(i.accessor);
1692 if constexpr (running_in_debug_mode())
1693 {
1694 // do this like this, because:
1695 // if we write
1696 // "Assert (IteratorState::past_the_end || !has_children())"
1697 // has_children() is called anyway, even if
1698 // state==IteratorState::past_the_end, and will then
1699 // throw the exception!
1700 if (this->state() != IteratorState::past_the_end)
1701 Assert(this->accessor.has_children() == false,
1702 ExcAssignmentOfInactiveObject());
1703 }
1704 return *this;
1705 }
1706
1707
1708 template <typename Accessor>
1709 inline TriaActiveIterator<Accessor> &
1710 TriaActiveIterator<Accessor>::operator=(const TriaIterator<Accessor> &i)
1711 {
1712 this->accessor.copy_from(i.accessor);
1713 if constexpr (running_in_debug_mode())
1714 {
1715 // do this like this, because:
1716 // if we write
1717 // "Assert (IteratorState::past_the_end || !has_children())"
1718 // has_children() is called anyway, even if
1719 // state==IteratorState::past_the_end, and will then
1720 // throw the exception!
1721 if (this->state() != IteratorState::past_the_end)
1722 Assert(this->accessor.has_children() == false,
1723 ExcAssignmentOfInactiveObject());
1724 }
1725 return *this;
1726 }
1727
1728
1729 template <typename Accessor>
1730 inline TriaActiveIterator<Accessor> &
1731 TriaActiveIterator<Accessor>::operator++()
1732 {
1733 while (TriaIterator<Accessor>::operator++(),
1734 (this->state() == IteratorState::valid))
1735 if (this->accessor.has_children() == false)
1736 return *this;
1737 return *this;
1738 }
1739
1740
1741 template <typename Accessor>
1742 inline TriaActiveIterator<Accessor>
1743 TriaActiveIterator<Accessor>::operator++(int)
1744 {
1745 TriaActiveIterator<Accessor> tmp(*this);
1746 operator++();
1747
1748 return tmp;
1749 }
1750
1751
1752 template <typename Accessor>
1753 inline TriaActiveIterator<Accessor> &
1754 TriaActiveIterator<Accessor>::operator--()
1755 {
1756 while (TriaIterator<Accessor>::operator--(),
1757 (this->state() == IteratorState::valid))
1758 if (this->accessor.has_children() == false)
1759 return *this;
1760 return *this;
1761 }
1762
1763
1764 template <typename Accessor>
1765 inline TriaActiveIterator<Accessor>
1766 TriaActiveIterator<Accessor>::operator--(int)
1767 {
1768 TriaActiveIterator<Accessor> tmp(*this);
1769 operator--();
1770
1771 return tmp;
1772 }
1773
1774 #endif
1775
1776 DEAL_II_NAMESPACE_CLOSE
1777
1778 #endif