Reference documentation for deal.II version GIT 1e9e64a91d 2022-09-28 19:20:02+00:00
\(\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 #include <deal.II/base/config.h>
21 
23 #include <deal.II/base/point.h>
24 
26 
27 #include <iterator>
28 #include <ostream>
29 
31 
32 // Forward declarations
33 #ifndef DOXYGEN
34 template <int dim, int spacedim>
35 class Triangulation;
36 template <int, int, int>
37 class TriaAccessorBase;
38 
39 template <typename>
40 class TriaIterator;
41 template <typename>
42 class TriaActiveIterator;
43 #endif
44 
45 
46 
47 // note: in non-debug mode, i.e. with optimizations, the file
48 // tria_iterator.templates.h is included at the end of this file.
49 // this includes a lot of templates and thus makes compilation
50 // slower, but at the same time allows for more aggressive
51 // inlining and thus faster code.
52 
53 
225 template <typename Accessor>
227 {
228 public:
234  using AccessorType = Accessor;
235 
241 
246 
259  explicit TriaRawIterator(const Accessor &a);
260 
265  template <typename OtherAccessor>
266  explicit TriaRawIterator(const OtherAccessor &a);
267 
275  const int level,
276  const int index,
277  const typename AccessorType::AccessorData *local_data = nullptr);
278 
288  template <typename OtherAccessor>
290 
297  const TriaAccessorBase<Accessor::structure_dimension,
298  Accessor::dimension,
299  Accessor::space_dimension> &tria_accessor,
300  const typename Accessor::AccessorData * local_data);
301 
306  template <typename OtherAccessor>
308 
313  template <typename OtherAccessor>
315 
332  const Accessor &
333  operator*() const;
334 
338  Accessor &
339  operator*();
340 
347  const Accessor *
348  operator->() const;
349 
353  Accessor *
354  operator->();
355 
356 
366  const Accessor &
367  access_any() const;
368 
376 
380  template <typename OtherAccessor = Accessor>
381  std::enable_if_t<std::is_convertible<OtherAccessor, Accessor>::value, bool>
383 
387  bool
388  operator!=(const TriaRawIterator &) const;
389 
415  bool
416  operator<(const TriaRawIterator &) const;
417 
422  bool
423  operator>(const TriaRawIterator &) const;
424 
435  operator++();
436 
450 
456  operator--();
457 
474  state() const;
475 
480  template <class StreamType>
481  void
482  print(StreamType &out) const;
483 
484 
489  std::size_t
490  memory_consumption() const;
491 
497  using iterator_category = std::bidirectional_iterator_tag;
498  using value_type = Accessor;
499  using difference_type = int;
500  using pointer = Accessor *;
501  using reference = Accessor &;
502 
511  Accessor,
512  << "You tried to dereference a cell iterator for which this "
513  << "is not possible. More information on this iterator: "
514  << "level=" << arg1.level() << ", index=" << arg1.index()
515  << ", state="
516  << (arg1.state() == IteratorState::valid ?
517  "valid" :
518  (arg1.state() == IteratorState::past_the_end ?
519  "past_the_end" :
520  "invalid")));
521 
526  Accessor,
527  << "You tried to dereference an iterator for which this "
528  << "is not possible. More information on this iterator: "
529  << "index=" << arg1.index() << ", state="
530  << (arg1.state() == IteratorState::valid ?
531  "valid" :
532  (arg1.state() == IteratorState::past_the_end ?
533  "past_the_end" :
534  "invalid")));
535 
544 
546 protected:
550  Accessor accessor;
551 
552 
553  // Make all other iterator class templates friends of this class. This is
554  // necessary for the implementation of conversion constructors.
555  //
556  // In fact, we would not need them to be friends if they were for different
557  // dimensions, but the compiler dislikes giving a fixed dimension and
558  // variable accessor since then it says that would be a partial
559  // specialization.
560  template <typename SomeAccessor>
561  friend class TriaRawIterator;
562  template <typename SomeAccessor>
563  friend class TriaIterator;
564  template <typename SomeAccessor>
565  friend class TriaActiveIterator;
566 };
567 
568 
576 template <typename Accessor>
577 class TriaIterator : public TriaRawIterator<Accessor>
578 {
579 public:
585 
590 
601 
613  const int level,
614  const int index,
615  const typename Accessor::AccessorData *local_data = nullptr);
616 
621  template <typename OtherAccessor>
622  explicit TriaIterator(const OtherAccessor &a);
623 
633  template <typename OtherAccessor>
635 
641  TriaIterator(const TriaAccessorBase<Accessor::structure_dimension,
642  Accessor::dimension,
643  Accessor::space_dimension> &tria_accessor,
644  const typename Accessor::AccessorData * local_data);
645 
651  template <typename OtherAccessor>
653 
658  template <typename OtherAccessor>
660 
666 
673 
678  template <class OtherAccessor>
681 
687  template <class OtherAccessor>
690 
702 
714 
721 
740 
745 };
746 
747 
757 template <typename Accessor>
758 class TriaActiveIterator : public TriaIterator<Accessor>
759 {
760 public:
766 
771 
782 
793 
805  const int level,
806  const int index,
807  const typename Accessor::AccessorData *local_data = nullptr);
808 
818  template <typename OtherAccessor>
820 
827  const TriaAccessorBase<Accessor::structure_dimension,
828  Accessor::dimension,
829  Accessor::space_dimension> &tria_accessor,
830  const typename Accessor::AccessorData * local_data);
831 
843  template <typename OtherAccessor>
845 
851 
858 
865 
870  template <class OtherAccessor>
873 
879  template <class OtherAccessor>
882 
888  template <class OtherAccessor>
891 
899 
915 
922 
940 
945 };
946 
947 
948 /*----------------------- Inline functions -------------------*/
949 
950 
951 template <typename Accessor>
953  : accessor(a)
954 {}
955 
956 
957 
958 template <typename Accessor>
959 template <typename OtherAccessor>
960 inline TriaRawIterator<Accessor>::TriaRawIterator(const OtherAccessor &a)
961  : accessor(a)
962 {}
963 
964 
965 
966 template <typename Accessor>
967 template <typename OtherAccessor>
970  : accessor(i.accessor)
971 {}
972 
973 
974 
975 template <typename Accessor>
976 template <typename OtherAccessor>
979  : accessor(i.accessor)
980 {}
981 
982 
983 
984 template <typename Accessor>
985 template <typename OtherAccessor>
988  : accessor(i.accessor)
989 {}
990 
991 
992 
993 template <typename Accessor>
994 inline const Accessor &
996 {
997  Assert(Accessor::structure_dimension != Accessor::dimension ||
998  state() == IteratorState::valid,
999  ExcDereferenceInvalidCell(accessor));
1000  Assert(Accessor::structure_dimension == Accessor::dimension ||
1001  state() == IteratorState::valid,
1002  ExcDereferenceInvalidObject(accessor));
1003 
1004  return accessor;
1005 }
1006 
1007 
1008 
1009 template <typename Accessor>
1010 inline Accessor &
1012 {
1013  Assert(Accessor::structure_dimension != Accessor::dimension ||
1014  state() == IteratorState::valid,
1015  ExcDereferenceInvalidCell(accessor));
1016  Assert(Accessor::structure_dimension == Accessor::dimension ||
1017  state() == IteratorState::valid,
1018  ExcDereferenceInvalidObject(accessor));
1019 
1020  return accessor;
1021 }
1022 
1023 
1024 
1025 template <typename Accessor>
1026 inline const Accessor &
1028 {
1029  return accessor;
1030 }
1031 
1032 
1033 
1034 template <typename Accessor>
1035 inline const Accessor *
1037 {
1038  return &(this->operator*());
1039 }
1040 
1041 
1042 
1043 template <typename Accessor>
1044 inline Accessor *
1046 {
1047  return &(this->operator*());
1048 }
1049 
1050 
1051 
1052 template <typename Accessor>
1055 {
1056  return accessor.state();
1057 }
1058 
1059 
1060 
1061 template <typename Accessor>
1062 inline bool
1064  const TriaRawIterator<Accessor> &other) const
1065 {
1066  Assert(state() != IteratorState::invalid,
1067  ExcDereferenceInvalidObject(accessor));
1068  Assert(other.state() != IteratorState::invalid,
1070 
1071  Assert(&accessor.get_triangulation() == &other.accessor.get_triangulation(),
1072  ExcInvalidComparison());
1073 
1074  // Deal with iterators past end
1075  if (state() == IteratorState::past_the_end)
1076  return false;
1077  if (other.state() == IteratorState::past_the_end)
1078  return true;
1079 
1080  return ((**this) < (*other));
1081 }
1082 
1083 
1084 
1085 template <typename Accessor>
1086 inline bool
1088  const TriaRawIterator<Accessor> &other) const
1089 {
1090  return (other < *this);
1091 }
1092 
1093 
1094 
1095 template <typename Accessor>
1098 {
1099  Assert(state() == IteratorState::valid, ExcAdvanceInvalidObject());
1100 
1101  ++accessor;
1102  return *this;
1103 }
1104 
1105 
1106 
1107 template <typename Accessor>
1110 {
1111  Assert(state() == IteratorState::valid, ExcAdvanceInvalidObject());
1112 
1113  --accessor;
1114  return *this;
1115 }
1116 
1117 
1118 
1119 template <typename Accessor>
1120 template <class StreamType>
1121 inline void
1122 TriaRawIterator<Accessor>::print(StreamType &out) const
1123 {
1124  if (Accessor::structure_dimension == Accessor::dimension)
1125  out << accessor.level() << '.' << accessor.index();
1126  else
1127  out << accessor.index();
1128 }
1129 
1130 
1131 
1132 template <typename Accessor>
1133 inline std::size_t
1135 {
1136  return sizeof(TriaRawIterator<Accessor>);
1137 }
1138 
1139 
1140 
1141 template <typename Accessor>
1142 template <typename OtherAccessor>
1144  const TriaIterator<OtherAccessor> &i)
1145  : TriaRawIterator<Accessor>(i.accessor)
1146 {}
1147 
1148 
1149 
1150 template <typename Accessor>
1151 template <typename OtherAccessor>
1154  : TriaRawIterator<Accessor>(i.accessor)
1155 {}
1156 
1157 
1158 
1159 template <typename Accessor>
1160 template <typename OtherAccessor>
1163  : TriaRawIterator<Accessor>(i.accessor)
1164 {
1165 #ifdef DEBUG
1166  // do this like this, because:
1167  // if we write
1168  // "Assert (IteratorState::past_the_end || used)"
1169  // used() is called anyway, even if
1170  // state==IteratorState::past_the_end, and will then
1171  // throw the exception!
1172  if (this->state() != IteratorState::past_the_end)
1173  Assert(this->accessor.used(), ExcAssignmentOfUnusedObject());
1174 #endif
1175 }
1176 
1177 template <typename Accessor>
1178 template <typename OtherAccessor>
1180  : TriaRawIterator<Accessor>(a)
1181 {
1182 #ifdef DEBUG
1183  // do this like this, because:
1184  // if we write
1185  // "Assert (IteratorState::past_the_end || used)"
1186  // used() is called anyway, even if
1187  // state==IteratorState::past_the_end, and will then
1188  // throw the exception!
1189  if (this->state() != IteratorState::past_the_end)
1190  Assert(this->accessor.used(), ExcAssignmentOfUnusedObject());
1191 #endif
1192 }
1193 
1194 template <typename Accessor>
1195 template <typename OtherAccessor>
1198  : TriaIterator<Accessor>(i.accessor)
1199 {}
1200 
1201 
1202 
1203 template <typename Accessor>
1204 template <typename OtherAccessor>
1207  : TriaIterator<Accessor>(i)
1208 {
1209 #ifdef DEBUG
1210  // do this like this, because:
1211  // if we write
1212  // "Assert (IteratorState::past_the_end || !has_children())"
1213  // has_children() is called anyway, even if
1214  // state==IteratorState::past_the_end, and will then
1215  // throw the exception!
1216  if (this->state() != IteratorState::past_the_end)
1217  Assert(this->accessor.has_children() == false,
1219 #endif
1220 }
1221 
1222 
1223 
1229 template <typename Accessor>
1230 inline std::ostream &
1231 operator<<(std::ostream &out, const TriaRawIterator<Accessor> &i)
1232 {
1233  i.print(out);
1234  return out;
1235 }
1236 
1237 
1238 
1244 template <typename Accessor>
1245 inline std::ostream &
1246 operator<<(std::ostream &out, const TriaIterator<Accessor> &i)
1247 {
1248  i.print(out);
1249  return out;
1250 }
1251 
1252 
1253 
1259 template <typename Accessor>
1260 inline std::ostream &
1261 operator<<(std::ostream &out, const TriaActiveIterator<Accessor> &i)
1262 {
1263  i.print(out);
1264  return out;
1265 }
1266 
1267 
1269 
1270 
1271 // if in optimized mode: include more templates
1272 #ifndef DEBUG
1273 # include "tria_iterator.templates.h"
1274 #endif
1275 
1276 #endif
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--(int)
TriaActiveIterator< Accessor > & operator=(const TriaActiveIterator< OtherAccessor > &)
TriaActiveIterator(const TriaActiveIterator< Accessor > &)
TriaActiveIterator< Accessor > & operator=(const TriaActiveIterator< Accessor > &)
TriaActiveIterator< Accessor > & operator=(const TriaIterator< Accessor > &)
TriaActiveIterator(const TriaRawIterator< Accessor > &)
TriaActiveIterator< Accessor > & operator=(const TriaRawIterator< OtherAccessor > &)
TriaActiveIterator< Accessor > & operator=(const TriaRawIterator< Accessor > &)
TriaActiveIterator(const TriaAccessorBase< Accessor::structure_dimension, Accessor::dimension, Accessor::space_dimension > &tria_accessor, const typename Accessor::AccessorData *local_data)
TriaActiveIterator< Accessor > operator++(int)
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--()
TriaActiveIterator< Accessor > & operator=(const TriaIterator< OtherAccessor > &)
TriaActiveIterator(const TriaIterator< Accessor > &)
typename TriaRawIterator< Accessor >::pointer pointer
TriaIterator(const TriaIterator< Accessor > &)
TriaIterator< Accessor > & operator=(const TriaIterator< OtherAccessor > &)
typename TriaRawIterator< Accessor >::iterator_category iterator_category
typename TriaRawIterator< Accessor >::value_type value_type
TriaIterator< Accessor > & operator--()
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++(int)
TriaIterator< Accessor > operator--(int)
TriaIterator< Accessor > & operator=(const TriaRawIterator< OtherAccessor > &)
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< Accessor > &)
TriaIterator(const TriaRawIterator< Accessor > &)
TriaIterator< Accessor > & operator++()
const Accessor * operator->() const
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)
TriaRawIterator & operator=(const TriaRawIterator &)
bool operator<(const TriaRawIterator &) const
std::enable_if_t< std::is_convertible< OtherAccessor, Accessor >::value, bool > operator==(const TriaRawIterator< OtherAccessor > &) const
TriaRawIterator(const TriaRawIterator &)
Accessor * pointer
IteratorState::IteratorStates state() const
void print(StreamType &out) const
friend class TriaRawIterator
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:457
#define DEAL_II_NAMESPACE_CLOSE
Definition: config.h:458
unsigned int level
Definition: grid_out.cc:4608
#define DeclException0(Exception0)
Definition: exceptions.h:464
#define Assert(cond, exc)
Definition: exceptions.h:1501
static ::ExceptionBase & ExcAdvanceInvalidObject()
static ::ExceptionBase & ExcAssignmentOfUnusedObject()
static ::ExceptionBase & ExcDereferenceInvalidObject(AccessorType arg1)
static ::ExceptionBase & ExcDereferenceInvalidCell(Accessor arg1)
#define DeclException1(Exception1, type1, outsequence)
Definition: exceptions.h:509
static ::ExceptionBase & ExcDereferenceInvalidObject(Accessor arg1)
static ::ExceptionBase & ExcAssignmentOfInactiveObject()
static ::ExceptionBase & ExcInvalidComparison()
@ past_the_end
Iterator reached end of container.
@ valid
Iterator points to a valid object.
@ invalid
Iterator is invalid, probably due to an error.