Reference documentation for deal.II version Git 497f915867 2021-09-17 22:46:48 +0200
\(\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 - 2021 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 
25 # include <deal.II/base/exceptions.h>
26 # include <deal.II/base/point.h>
27 
29 
30 # include <iterator>
31 # include <ostream>
32 
34 
35 // Forward declarations
36 # ifndef DOXYGEN
37 template <int dim, int spacedim>
38 class Triangulation;
39 template <int, int, int>
40 class TriaAccessorBase;
41 
42 template <typename>
43 class TriaIterator;
44 template <typename>
45 class TriaActiveIterator;
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 
228 template <typename Accessor>
230 {
231 public:
237  using AccessorType = Accessor;
238 
243  TriaRawIterator();
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 
378  operator=(const TriaRawIterator &);
379 
383  template <typename OtherAccessor = Accessor>
384  typename std::enable_if<std::is_convertible<OtherAccessor, Accessor>::value,
385  bool>::type
387 
391  bool
392  operator!=(const TriaRawIterator &) const;
393 
419  bool
420  operator<(const TriaRawIterator &) const;
421 
426  bool
427  operator>(const TriaRawIterator &) const;
428 
439  operator++();
440 
453  operator++(int);
454 
460  operator--();
461 
471  operator--(int);
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 
550 protected:
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 
580 template <typename Accessor>
581 class TriaIterator : public TriaRawIterator<Accessor>
582 {
583 public:
588  TriaIterator();
589 
594 
605 
615  TriaIterator(
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 
705  operator++();
706 
717  operator++(int);
718 
724  operator--();
725 
730  operator--(int);
738  using iterator_category =
744 
748  DeclException0(ExcAssignmentOfUnusedObject);
749 };
750 
751 
761 template <typename Accessor>
762 class TriaActiveIterator : public TriaIterator<Accessor>
763 {
764 public:
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 
902  operator++();
903 
918  operator++(int);
919 
925  operator--();
926 
931  operator--(int);
944 
948  DeclException0(ExcAssignmentOfInactiveObject);
949 };
950 
951 
952 /*----------------------- Inline functions -------------------*/
953 
954 
955 template <typename Accessor>
957  : accessor(a)
958 {}
959 
960 
961 
962 template <typename Accessor>
963 template <typename OtherAccessor>
964 inline TriaRawIterator<Accessor>::TriaRawIterator(const OtherAccessor &a)
965  : accessor(a)
966 {}
967 
968 
969 
970 template <typename Accessor>
971 template <typename OtherAccessor>
974  : accessor(i.accessor)
975 {}
976 
977 
978 
979 template <typename Accessor>
980 template <typename OtherAccessor>
983  : accessor(i.accessor)
984 {}
985 
986 
987 
988 template <typename Accessor>
989 template <typename OtherAccessor>
992  : accessor(i.accessor)
993 {}
994 
995 
996 
997 template <typename Accessor>
998 inline const Accessor &
1000 {
1001  Assert(Accessor::structure_dimension != Accessor::dimension ||
1004  Assert(Accessor::structure_dimension == Accessor::dimension ||
1007 
1008  return accessor;
1009 }
1010 
1011 
1012 
1013 template <typename Accessor>
1014 inline Accessor &
1016 {
1017  Assert(Accessor::structure_dimension != Accessor::dimension ||
1020  Assert(Accessor::structure_dimension == Accessor::dimension ||
1023 
1024  return accessor;
1025 }
1026 
1027 
1028 
1029 template <typename Accessor>
1030 inline const Accessor &
1032 {
1033  return accessor;
1034 }
1035 
1036 
1037 
1038 template <typename Accessor>
1039 inline const Accessor *
1041 {
1042  return &(this->operator*());
1043 }
1044 
1045 
1046 
1047 template <typename Accessor>
1048 inline Accessor *
1050 {
1051  return &(this->operator*());
1052 }
1053 
1054 
1055 
1056 template <typename Accessor>
1059 {
1060  return accessor.state();
1061 }
1062 
1063 
1064 
1065 template <typename Accessor>
1066 inline bool
1068  const TriaRawIterator<Accessor> &other) const
1069 {
1072  Assert(other.state() != IteratorState::invalid,
1074 
1075  Assert(&accessor.get_triangulation() == &other.accessor.get_triangulation(),
1077 
1078  // Deal with iterators past end
1080  return false;
1081  if (other.state() == IteratorState::past_the_end)
1082  return true;
1083 
1084  return ((**this) < (*other));
1085 }
1086 
1087 
1088 
1089 template <typename Accessor>
1090 inline bool
1092  const TriaRawIterator<Accessor> &other) const
1093 {
1094  return (other < *this);
1095 }
1096 
1097 
1098 
1099 template <typename Accessor>
1102 {
1104 
1105  ++accessor;
1106  return *this;
1107 }
1108 
1109 
1110 
1111 template <typename Accessor>
1114 {
1116 
1117  --accessor;
1118  return *this;
1119 }
1120 
1121 
1122 
1123 template <typename Accessor>
1124 template <class StreamType>
1125 inline void
1126 TriaRawIterator<Accessor>::print(StreamType &out) const
1127 {
1128  if (Accessor::structure_dimension == Accessor::dimension)
1129  out << accessor.level() << "." << accessor.index();
1130  else
1131  out << accessor.index();
1132 }
1133 
1134 
1135 
1136 template <typename Accessor>
1137 inline std::size_t
1139 {
1140  return sizeof(TriaRawIterator<Accessor>);
1141 }
1142 
1143 
1144 
1145 template <typename Accessor>
1146 template <typename OtherAccessor>
1148  const TriaIterator<OtherAccessor> &i)
1149  : TriaRawIterator<Accessor>(i.accessor)
1150 {}
1151 
1152 
1153 
1154 template <typename Accessor>
1155 template <typename OtherAccessor>
1158  : TriaRawIterator<Accessor>(i.accessor)
1159 {}
1160 
1161 
1162 
1163 template <typename Accessor>
1164 template <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)
1177  Assert(this->accessor.used(), ExcAssignmentOfUnusedObject());
1178 # endif
1179 }
1180 
1181 template <typename Accessor>
1182 template <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)
1194  Assert(this->accessor.used(), ExcAssignmentOfUnusedObject());
1195 # endif
1196 }
1197 
1198 template <typename Accessor>
1199 template <typename OtherAccessor>
1202  : TriaIterator<Accessor>(i.accessor)
1203 {}
1204 
1205 
1206 
1207 template <typename Accessor>
1208 template <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 
1233 template <typename Accessor>
1234 inline std::ostream &
1235 operator<<(std::ostream &out, const TriaRawIterator<Accessor> &i)
1236 {
1237  i.print(out);
1238  return out;
1239 }
1240 
1241 
1242 
1248 template <typename Accessor>
1249 inline std::ostream &
1250 operator<<(std::ostream &out, const TriaIterator<Accessor> &i)
1251 {
1252  i.print(out);
1253  return out;
1254 }
1255 
1256 
1257 
1263 template <typename Accessor>
1264 inline std::ostream &
1265 operator<<(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 ---------------------------*/
friend class TriaIterator
typename TriaRawIterator< Accessor >::reference reference
Iterator is invalid, probably due to an error.
const Accessor * operator->() const
static ::ExceptionBase & ExcInvalidComparison()
static ::ExceptionBase & ExcAdvanceInvalidObject()
const Accessor & operator*() const
static ::ExceptionBase & ExcAssignmentOfInactiveObject()
bool operator>(const TriaRawIterator &) const
Accessor value_type
std::enable_if< std::is_convertible< OtherAccessor, Accessor >::value, bool >::type operator==(const TriaRawIterator< OtherAccessor > &) const
typename TriaRawIterator< Accessor >::value_type value_type
typename TriaRawIterator< Accessor >::iterator_category iterator_category
#define DeclException1(Exception1, type1, outsequence)
Definition: exceptions.h:509
Accessor AccessorType
typename TriaRawIterator< Accessor >::pointer pointer
#define Assert(cond, exc)
Definition: exceptions.h:1461
Accessor & reference
TriaRawIterator & operator++()
#define DeclException0(Exception0)
Definition: exceptions.h:464
Accessor * pointer
#define DEAL_II_NAMESPACE_CLOSE
Definition: config.h:401
unsigned int level
Definition: grid_out.cc:4589
static ::ExceptionBase & ExcDereferenceInvalidObject(Accessor arg1)
bool operator!=(const TriaRawIterator &) const
TriaRawIterator & operator--()
static ::ExceptionBase & ExcAssignmentOfUnusedObject()
static ::ExceptionBase & ExcDereferenceInvalidCell(Accessor arg1)
friend class TriaActiveIterator
#define DEAL_II_NAMESPACE_OPEN
Definition: config.h:400
TriaRawIterator & operator=(const TriaRawIterator &)
Iterator reached end of container.
const Accessor & access_any() const
Iterator points to a valid object.
void print(StreamType &out) const
typename TriaRawIterator< Accessor >::difference_type difference_type
IteratorState::IteratorStates state() const
std::bidirectional_iterator_tag iterator_category
bool operator<(const TriaRawIterator &) const
std::size_t memory_consumption() const