Reference documentation for deal.II version 9.4.0
\(\newcommand{\dealvcentcolon}{\mathrel{\mathop{:}}}\) \(\newcommand{\dealcoloneq}{\dealvcentcolon\mathrel{\mkern-1.2mu}=}\) \(\newcommand{\jump}[1]{\left[\!\left[ #1 \right]\!\right]}\) \(\newcommand{\average}[1]{\left\{\!\left\{ #1 \right\}\!\right\}}\)
tria_iterator.h
Go to the documentation of this file.
1// ---------------------------------------------------------------------
2//
3// Copyright (C) 1998 - 2022 by the deal.II authors
4//
5// This file is part of the deal.II library.
6//
7// The deal.II library is free software; you can use it, redistribute
8// it, and/or modify it under the terms of the GNU Lesser General
9// Public License as published by the Free Software Foundation; either
10// version 2.1 of the License, or (at your option) any later version.
11// The full text of the license can be found in the file LICENSE.md at
12// the top level directory of deal.II.
13//
14// ---------------------------------------------------------------------
15
16#ifndef dealii_tria_iterator_h
17# define dealii_tria_iterator_h
18
19
20/*---------------------------- tria-iterator.h ---------------------------*/
21
22
23# include <deal.II/base/config.h>
24
26# include <deal.II/base/point.h>
27
29
30# include <iterator>
31# include <ostream>
32
34
35// Forward declarations
36# ifndef DOXYGEN
37template <int dim, int spacedim>
38class Triangulation;
39template <int, int, int>
41
42template <typename>
43class TriaIterator;
44template <typename>
46# endif
47
48
49
50// note: in non-debug mode, i.e. with optimizations, the file
51// tria_iterator.templates.h is included at the end of this file.
52// this includes a lot of templates and thus makes compilation
53// slower, but at the same time allows for more aggressive
54// inlining and thus faster code.
55
56
228template <typename Accessor>
230{
231public:
237 using AccessorType = Accessor;
238
244
249
262 explicit TriaRawIterator(const Accessor &a);
263
268 template <typename OtherAccessor>
269 explicit TriaRawIterator(const OtherAccessor &a);
270
278 const int level,
279 const int index,
280 const typename AccessorType::AccessorData *local_data = nullptr);
281
291 template <typename OtherAccessor>
293
300 const TriaAccessorBase<Accessor::structure_dimension,
301 Accessor::dimension,
302 Accessor::space_dimension> &tria_accessor,
303 const typename Accessor::AccessorData * local_data);
304
309 template <typename OtherAccessor>
311
316 template <typename OtherAccessor>
318
335 const Accessor &
336 operator*() const;
337
341 Accessor &
342 operator*();
343
350 const Accessor *
351 operator->() const;
352
356 Accessor *
357 operator->();
358
359
369 const Accessor &
370 access_any() const;
371
379
383 template <typename OtherAccessor = Accessor>
384 typename std::enable_if<std::is_convertible<OtherAccessor, Accessor>::value,
385 bool>::type
387
391 bool
393
419 bool
420 operator<(const TriaRawIterator &) const;
421
426 bool
427 operator>(const TriaRawIterator &) const;
428
439 operator++();
440
454
460 operator--();
461
478 state() const;
479
484 template <class StreamType>
485 void
486 print(StreamType &out) const;
487
488
493 std::size_t
494 memory_consumption() const;
495
501 using iterator_category = std::bidirectional_iterator_tag;
502 using value_type = Accessor;
504 using pointer = Accessor *;
505 using reference = Accessor &;
506
515 Accessor,
516 << "You tried to dereference a cell iterator for which this "
517 << "is not possible. More information on this iterator: "
518 << "level=" << arg1.level() << ", index=" << arg1.index()
519 << ", state="
520 << (arg1.state() == IteratorState::valid ?
521 "valid" :
522 (arg1.state() == IteratorState::past_the_end ?
523 "past_the_end" :
524 "invalid")));
525
530 Accessor,
531 << "You tried to dereference an iterator for which this "
532 << "is not possible. More information on this iterator: "
533 << "index=" << arg1.index() << ", state="
534 << (arg1.state() == IteratorState::valid ?
535 "valid" :
536 (arg1.state() == IteratorState::past_the_end ?
537 "past_the_end" :
538 "invalid")));
539
548
550protected:
554 Accessor accessor;
555
556
557 // Make all other iterator class templates friends of this class. This is
558 // necessary for the implementation of conversion constructors.
559 //
560 // In fact, we would not need them to be friends if they were for different
561 // dimensions, but the compiler dislikes giving a fixed dimension and
562 // variable accessor since then it says that would be a partial
563 // specialization.
564 template <typename SomeAccessor>
565 friend class TriaRawIterator;
566 template <typename SomeAccessor>
567 friend class TriaIterator;
568 template <typename SomeAccessor>
569 friend class TriaActiveIterator;
570};
571
572
580template <typename Accessor>
581class TriaIterator : public TriaRawIterator<Accessor>
582{
583public:
589
594
605
617 const int level,
618 const int index,
619 const typename Accessor::AccessorData *local_data = nullptr);
620
625 template <typename OtherAccessor>
626 explicit TriaIterator(const OtherAccessor &a);
627
637 template <typename OtherAccessor>
639
645 TriaIterator(const TriaAccessorBase<Accessor::structure_dimension,
646 Accessor::dimension,
647 Accessor::space_dimension> &tria_accessor,
648 const typename Accessor::AccessorData * local_data);
649
655 template <typename OtherAccessor>
657
662 template <typename OtherAccessor>
664
670
677
682 template <class OtherAccessor>
685
691 template <class OtherAccessor>
694
706
718
725
744
749};
750
751
761template <typename Accessor>
762class TriaActiveIterator : public TriaIterator<Accessor>
763{
764public:
770
775
786
797
809 const int level,
810 const int index,
811 const typename Accessor::AccessorData *local_data = nullptr);
812
822 template <typename OtherAccessor>
824
831 const TriaAccessorBase<Accessor::structure_dimension,
832 Accessor::dimension,
833 Accessor::space_dimension> &tria_accessor,
834 const typename Accessor::AccessorData * local_data);
835
847 template <typename OtherAccessor>
849
855
862
869
874 template <class OtherAccessor>
877
883 template <class OtherAccessor>
886
892 template <class OtherAccessor>
895
903
919
926
944
949};
950
951
952/*----------------------- Inline functions -------------------*/
953
954
955template <typename Accessor>
957 : accessor(a)
958{}
959
960
961
962template <typename Accessor>
963template <typename OtherAccessor>
964inline TriaRawIterator<Accessor>::TriaRawIterator(const OtherAccessor &a)
965 : accessor(a)
966{}
967
968
969
970template <typename Accessor>
971template <typename OtherAccessor>
974 : accessor(i.accessor)
975{}
976
977
978
979template <typename Accessor>
980template <typename OtherAccessor>
983 : accessor(i.accessor)
984{}
985
986
987
988template <typename Accessor>
989template <typename OtherAccessor>
992 : accessor(i.accessor)
993{}
994
995
996
997template <typename Accessor>
998inline const Accessor &
1000{
1001 Assert(Accessor::structure_dimension != Accessor::dimension ||
1002 state() == IteratorState::valid,
1003 ExcDereferenceInvalidCell(accessor));
1004 Assert(Accessor::structure_dimension == Accessor::dimension ||
1005 state() == IteratorState::valid,
1006 ExcDereferenceInvalidObject(accessor));
1007
1008 return accessor;
1009}
1010
1011
1012
1013template <typename Accessor>
1014inline Accessor &
1016{
1017 Assert(Accessor::structure_dimension != Accessor::dimension ||
1018 state() == IteratorState::valid,
1019 ExcDereferenceInvalidCell(accessor));
1020 Assert(Accessor::structure_dimension == Accessor::dimension ||
1021 state() == IteratorState::valid,
1022 ExcDereferenceInvalidObject(accessor));
1023
1024 return accessor;
1025}
1026
1027
1028
1029template <typename Accessor>
1030inline const Accessor &
1032{
1033 return accessor;
1034}
1035
1036
1037
1038template <typename Accessor>
1039inline const Accessor *
1041{
1042 return &(this->operator*());
1043}
1044
1045
1046
1047template <typename Accessor>
1048inline Accessor *
1050{
1051 return &(this->operator*());
1052}
1053
1054
1055
1056template <typename Accessor>
1059{
1060 return accessor.state();
1061}
1062
1063
1064
1065template <typename Accessor>
1066inline bool
1068 const TriaRawIterator<Accessor> &other) const
1069{
1070 Assert(state() != IteratorState::invalid,
1071 ExcDereferenceInvalidObject(accessor));
1074
1075 Assert(&accessor.get_triangulation() == &other.accessor.get_triangulation(),
1076 ExcInvalidComparison());
1077
1078 // Deal with iterators past end
1079 if (state() == IteratorState::past_the_end)
1080 return false;
1081 if (other.state() == IteratorState::past_the_end)
1082 return true;
1083
1084 return ((**this) < (*other));
1085}
1086
1087
1088
1089template <typename Accessor>
1090inline bool
1092 const TriaRawIterator<Accessor> &other) const
1093{
1094 return (other < *this);
1095}
1096
1097
1098
1099template <typename Accessor>
1102{
1103 Assert(state() == IteratorState::valid, ExcAdvanceInvalidObject());
1104
1105 ++accessor;
1106 return *this;
1107}
1108
1109
1110
1111template <typename Accessor>
1114{
1115 Assert(state() == IteratorState::valid, ExcAdvanceInvalidObject());
1116
1117 --accessor;
1118 return *this;
1119}
1120
1121
1122
1123template <typename Accessor>
1124template <class StreamType>
1125inline void
1127{
1128 if (Accessor::structure_dimension == Accessor::dimension)
1129 out << accessor.level() << '.' << accessor.index();
1130 else
1131 out << accessor.index();
1132}
1133
1134
1135
1136template <typename Accessor>
1137inline std::size_t
1139{
1140 return sizeof(TriaRawIterator<Accessor>);
1141}
1142
1143
1144
1145template <typename Accessor>
1146template <typename OtherAccessor>
1149 : TriaRawIterator<Accessor>(i.accessor)
1150{}
1151
1152
1153
1154template <typename Accessor>
1155template <typename OtherAccessor>
1158 : TriaRawIterator<Accessor>(i.accessor)
1159{}
1160
1161
1162
1163template <typename Accessor>
1164template <typename OtherAccessor>
1167 : TriaRawIterator<Accessor>(i.accessor)
1168{
1169# ifdef DEBUG
1170 // do this like this, because:
1171 // if we write
1172 // "Assert (IteratorState::past_the_end || used)"
1173 // used() is called anyway, even if
1174 // state==IteratorState::past_the_end, and will then
1175 // throw the exception!
1176 if (this->state() != IteratorState::past_the_end)
1178# endif
1179}
1180
1181template <typename Accessor>
1182template <typename OtherAccessor>
1184 : TriaRawIterator<Accessor>(a)
1185{
1186# ifdef DEBUG
1187 // do this like this, because:
1188 // if we write
1189 // "Assert (IteratorState::past_the_end || used)"
1190 // used() 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)
1195# endif
1196}
1197
1198template <typename Accessor>
1199template <typename OtherAccessor>
1202 : TriaIterator<Accessor>(i.accessor)
1203{}
1204
1205
1206
1207template <typename Accessor>
1208template <typename OtherAccessor>
1211 : TriaIterator<Accessor>(i)
1212{
1213# ifdef DEBUG
1214 // do this like this, because:
1215 // if we write
1216 // "Assert (IteratorState::past_the_end || !has_children())"
1217 // has_children() is called anyway, even if
1218 // state==IteratorState::past_the_end, and will then
1219 // throw the exception!
1220 if (this->state() != IteratorState::past_the_end)
1221 Assert(this->accessor.has_children() == false,
1223# endif
1224}
1225
1226
1227
1233template <typename Accessor>
1234inline std::ostream &
1235operator<<(std::ostream &out, const TriaRawIterator<Accessor> &i)
1236{
1237 i.print(out);
1238 return out;
1239}
1240
1241
1242
1248template <typename Accessor>
1249inline std::ostream &
1250operator<<(std::ostream &out, const TriaIterator<Accessor> &i)
1251{
1252 i.print(out);
1253 return out;
1254}
1255
1256
1257
1263template <typename Accessor>
1264inline std::ostream &
1265operator<<(std::ostream &out, const TriaActiveIterator<Accessor> &i)
1266{
1267 i.print(out);
1268 return out;
1269}
1270
1271
1273
1274
1275// if in optimized mode: include more templates
1276# ifndef DEBUG
1277# include "tria_iterator.templates.h"
1278# endif
1279
1280
1281/*---------------------------- tria-iterator.h ---------------------------*/
1282#endif
1283/*---------------------------- tria-iterator.h ---------------------------*/
OutputOperator< VectorType > & operator<<(OutputOperator< VectorType > &out, unsigned int step)
Definition: operator.h:165
Point< dim, typename ProductType< Number, typename EnableIfScalar< OtherNumber >::type >::type > operator*(const OtherNumber) const
TriaActiveIterator< Accessor > & operator=(const TriaIterator< OtherAccessor > &)
TriaActiveIterator(const TriaActiveIterator< Accessor > &)
TriaActiveIterator< Accessor > & operator=(const TriaRawIterator< Accessor > &)
TriaActiveIterator< Accessor > operator--(int)
TriaActiveIterator(const TriaRawIterator< Accessor > &)
TriaActiveIterator< Accessor > & operator=(const TriaActiveIterator< Accessor > &)
TriaActiveIterator< Accessor > & operator=(const TriaActiveIterator< OtherAccessor > &)
TriaActiveIterator< Accessor > & operator--()
TriaActiveIterator(const TriaAccessorBase< Accessor::structure_dimension, Accessor::dimension, Accessor::space_dimension > &tria_accessor, const typename Accessor::AccessorData *local_data)
TriaActiveIterator< Accessor > & operator=(const TriaIterator< Accessor > &)
TriaActiveIterator(const Triangulation< Accessor::dimension, Accessor::space_dimension > *parent, const int level, const int index, const typename Accessor::AccessorData *local_data=nullptr)
TriaActiveIterator< Accessor > & operator++()
TriaActiveIterator< Accessor > & operator=(const TriaRawIterator< OtherAccessor > &)
TriaActiveIterator< Accessor > operator++(int)
TriaActiveIterator(const TriaIterator< Accessor > &)
typename TriaRawIterator< Accessor >::pointer pointer
TriaIterator(const TriaIterator< Accessor > &)
TriaIterator< Accessor > & operator++()
TriaIterator< Accessor > operator--(int)
typename TriaRawIterator< Accessor >::iterator_category iterator_category
TriaIterator< Accessor > & operator=(const TriaRawIterator< OtherAccessor > &)
typename TriaRawIterator< Accessor >::value_type value_type
TriaIterator< Accessor > operator++(int)
TriaIterator< Accessor > & operator=(const TriaIterator< Accessor > &)
typename TriaRawIterator< Accessor >::difference_type difference_type
TriaIterator< Accessor > & operator=(const TriaRawIterator< Accessor > &)
TriaIterator(const TriaAccessorBase< Accessor::structure_dimension, Accessor::dimension, Accessor::space_dimension > &tria_accessor, const typename Accessor::AccessorData *local_data)
typename TriaRawIterator< Accessor >::reference reference
TriaIterator< Accessor > & operator--()
TriaIterator(const Triangulation< Accessor::dimension, Accessor::space_dimension > *parent, const int level, const int index, const typename Accessor::AccessorData *local_data=nullptr)
TriaIterator< Accessor > & operator=(const TriaIterator< OtherAccessor > &)
TriaIterator(const TriaRawIterator< Accessor > &)
const Accessor * operator->() const
TriaRawIterator & operator=(const TriaRawIterator &)
bool operator>(const TriaRawIterator &) const
const Accessor & operator*() const
Accessor value_type
std::size_t memory_consumption() const
TriaRawIterator(const Triangulation< Accessor::dimension, Accessor::space_dimension > *parent, const int level, const int index, const typename AccessorType::AccessorData *local_data=nullptr)
TriaRawIterator(const TriaAccessorBase< Accessor::structure_dimension, Accessor::dimension, Accessor::space_dimension > &tria_accessor, const typename Accessor::AccessorData *local_data)
std::enable_if< std::is_convertible< OtherAccessor, Accessor >::value, bool >::type operator==(const TriaRawIterator< OtherAccessor > &) const
bool operator<(const TriaRawIterator &) const
TriaRawIterator(const TriaRawIterator &)
Accessor * pointer
IteratorState::IteratorStates state() const
void print(StreamType &out) const
Accessor AccessorType
bool operator!=(const TriaRawIterator &) const
TriaRawIterator operator++(int)
std::bidirectional_iterator_tag iterator_category
TriaRawIterator & operator++()
const Accessor & access_any() const
Accessor & reference
TriaRawIterator & operator--()
TriaRawIterator operator--(int)
#define DEAL_II_NAMESPACE_OPEN
Definition: config.h:442
#define DEAL_II_NAMESPACE_CLOSE
Definition: config.h:443
unsigned int level
Definition: grid_out.cc:4606
static ::ExceptionBase & ExcAssignmentOfUnusedObject()
#define DeclException0(Exception0)
Definition: exceptions.h:464
static ::ExceptionBase & ExcAssignmentOfInactiveObject()
#define Assert(cond, exc)
Definition: exceptions.h:1473
static ::ExceptionBase & ExcAdvanceInvalidObject()
friend class TriaRawIterator
static ::ExceptionBase & ExcDereferenceInvalidObject(AccessorType arg1)
static ::ExceptionBase & ExcInvalidComparison()
#define DeclException1(Exception1, type1, outsequence)
Definition: exceptions.h:509
static ::ExceptionBase & ExcDereferenceInvalidObject(Accessor arg1)
static ::ExceptionBase & ExcDereferenceInvalidCell(Accessor arg1)
@ past_the_end
Iterator reached end of container.
@ valid
Iterator points to a valid object.
@ invalid
Iterator is invalid, probably due to an error.