Reference documentation for deal.II version GIT 8ad845fa53 2023-12-10 20:50: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 - 2023 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 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 // note: in non-debug mode, i.e. with optimizations, the file
49 // tria_iterator.templates.h is included at the end of this file.
50 // this includes a lot of templates and thus makes compilation
51 // slower, but at the same time allows for more aggressive
52 // inlining and thus faster code.
53 
54 
226 template <typename Accessor>
228 {
229 public:
235  using AccessorType = Accessor;
236 
242 
247 
260  explicit TriaRawIterator(const Accessor &a);
261 
266  template <typename OtherAccessor>
267  explicit TriaRawIterator(const OtherAccessor &a);
268 
276  const int level,
277  const int index,
278  const typename AccessorType::AccessorData *local_data = nullptr);
279 
289  template <typename OtherAccessor>
291 
298  const TriaAccessorBase<Accessor::structure_dimension,
299  Accessor::dimension,
300  Accessor::space_dimension> &tria_accessor,
301  const typename Accessor::AccessorData *local_data);
302 
307  template <typename OtherAccessor>
309 
314  template <typename OtherAccessor>
316 
334  Accessor
335  operator*() const;
336 
344  const Accessor *
345  operator->() const;
346 
350  Accessor *
351  operator->();
352 
353 
363  const Accessor &
364  access_any() const;
365 
373 
377  template <typename OtherAccessor = Accessor>
378  std::enable_if_t<std::is_convertible_v<OtherAccessor, Accessor>, bool>
380 
384  bool
385  operator!=(const TriaRawIterator &) const;
386 
412  bool
413  operator<(const TriaRawIterator &) const;
414 
419  bool
420  operator>(const TriaRawIterator &) const;
421 
432  operator++();
433 
447 
453  operator--();
454 
471  state() const;
472 
477  template <typename StreamType>
478  void
479  print(StreamType &out) const;
480 
481 
486  std::size_t
487  memory_consumption() const;
488 
494  using iterator_category = std::bidirectional_iterator_tag;
495  using value_type = Accessor;
496  using difference_type = int;
497  using pointer = Accessor *;
498  using reference = Accessor &;
499 
508  Accessor,
509  << "You tried to dereference a cell iterator for which this "
510  << "is not possible. More information on this iterator: "
511  << "level=" << arg1.level() << ", index=" << arg1.index()
512  << ", state="
513  << (arg1.state() == IteratorState::valid ?
514  "valid" :
515  (arg1.state() == IteratorState::past_the_end ?
516  "past_the_end" :
517  "invalid")));
518 
523  Accessor,
524  << "You tried to dereference an iterator for which this "
525  << "is not possible. More information on this iterator: "
526  << "index=" << arg1.index() << ", state="
527  << (arg1.state() == IteratorState::valid ?
528  "valid" :
529  (arg1.state() == IteratorState::past_the_end ?
530  "past_the_end" :
531  "invalid")));
532 
541 
543 protected:
547  Accessor accessor;
548 
549 
550  // Make all other iterator class templates friends of this class. This is
551  // necessary for the implementation of conversion constructors.
552  //
553  // In fact, we would not need them to be friends if they were for different
554  // dimensions, but the compiler dislikes giving a fixed dimension and
555  // variable accessor since then it says that would be a partial
556  // specialization.
557  template <typename SomeAccessor>
558  friend class TriaRawIterator;
559  template <typename SomeAccessor>
560  friend class TriaIterator;
561  template <typename SomeAccessor>
562  friend class TriaActiveIterator;
563 };
564 
565 
573 template <typename Accessor>
574 class TriaIterator : public TriaRawIterator<Accessor>
575 {
576 public:
582 
587 
598 
610  const int level,
611  const int index,
612  const typename Accessor::AccessorData *local_data = nullptr);
613 
618  template <typename OtherAccessor>
619  explicit TriaIterator(const OtherAccessor &a);
620 
630  template <typename OtherAccessor>
632 
638  TriaIterator(const TriaAccessorBase<Accessor::structure_dimension,
639  Accessor::dimension,
640  Accessor::space_dimension> &tria_accessor,
641  const typename Accessor::AccessorData *local_data);
642 
648  template <typename OtherAccessor>
650 
655  template <typename OtherAccessor>
657 
663 
670 
675  template <class OtherAccessor>
678 
684  template <class OtherAccessor>
687 
699 
711 
718 
737 
742 };
743 
744 
754 template <typename Accessor>
755 class TriaActiveIterator : public TriaIterator<Accessor>
756 {
757 public:
763 
768 
779 
790 
802  const int level,
803  const int index,
804  const typename Accessor::AccessorData *local_data = nullptr);
805 
815  template <typename OtherAccessor>
817 
824  const TriaAccessorBase<Accessor::structure_dimension,
825  Accessor::dimension,
826  Accessor::space_dimension> &tria_accessor,
827  const typename Accessor::AccessorData *local_data);
828 
840  template <typename OtherAccessor>
842 
848 
855 
862 
867  template <class OtherAccessor>
870 
876  template <class OtherAccessor>
879 
885  template <class OtherAccessor>
888 
896 
912 
919 
937 
942 };
943 
944 
945 /*----------------------- Inline functions -------------------*/
946 
947 
948 template <typename Accessor>
950  : accessor(a)
951 {}
952 
953 
954 
955 template <typename Accessor>
956 template <typename OtherAccessor>
957 inline TriaRawIterator<Accessor>::TriaRawIterator(const OtherAccessor &a)
958  : accessor(a)
959 {}
960 
961 
962 
963 template <typename Accessor>
964 template <typename OtherAccessor>
967  : accessor(i.accessor)
968 {}
969 
970 
971 
972 template <typename Accessor>
973 template <typename OtherAccessor>
976  : accessor(i.accessor)
977 {}
978 
979 
980 
981 template <typename Accessor>
982 template <typename OtherAccessor>
985  : accessor(i.accessor)
986 {}
987 
988 
989 
990 template <typename Accessor>
991 inline Accessor
993 {
994  Assert(Accessor::structure_dimension != Accessor::dimension ||
995  state() == IteratorState::valid,
996  ExcDereferenceInvalidCell(accessor));
997  Assert(Accessor::structure_dimension == Accessor::dimension ||
998  state() == IteratorState::valid,
999  ExcDereferenceInvalidObject(accessor));
1000 
1001  return accessor;
1002 }
1003 
1004 
1005 
1006 template <typename Accessor>
1007 inline const Accessor &
1009 {
1010  return accessor;
1011 }
1012 
1013 
1014 
1015 template <typename Accessor>
1016 inline const Accessor *
1018 {
1019  return &accessor;
1020 }
1021 
1022 
1023 
1024 template <typename Accessor>
1025 inline Accessor *
1027 {
1028  return &accessor;
1029 }
1030 
1031 
1032 
1033 template <typename Accessor>
1036 {
1037  return accessor.state();
1038 }
1039 
1040 
1041 
1042 template <typename Accessor>
1043 inline bool
1045  const TriaRawIterator<Accessor> &other) const
1046 {
1047  Assert(state() != IteratorState::invalid,
1048  ExcDereferenceInvalidObject(accessor));
1049  Assert(other.state() != IteratorState::invalid,
1051 
1052  Assert(&accessor.get_triangulation() == &other.accessor.get_triangulation(),
1053  ExcInvalidComparison());
1054 
1055  // Deal with iterators past end
1056  if (state() == IteratorState::past_the_end)
1057  return false;
1058  if (other.state() == IteratorState::past_the_end)
1059  return true;
1060 
1061  return ((**this) < (*other));
1062 }
1063 
1064 
1065 
1066 template <typename Accessor>
1067 inline bool
1069  const TriaRawIterator<Accessor> &other) const
1070 {
1071  return (other < *this);
1072 }
1073 
1074 
1075 
1076 template <typename Accessor>
1079 {
1080  Assert(state() == IteratorState::valid, ExcAdvanceInvalidObject());
1081 
1082  ++accessor;
1083  return *this;
1084 }
1085 
1086 
1087 
1088 template <typename Accessor>
1091 {
1092  Assert(state() == IteratorState::valid, ExcAdvanceInvalidObject());
1093 
1094  --accessor;
1095  return *this;
1096 }
1097 
1098 
1099 
1100 template <typename Accessor>
1101 template <typename StreamType>
1102 inline void
1103 TriaRawIterator<Accessor>::print(StreamType &out) const
1104 {
1105  if (Accessor::structure_dimension == Accessor::dimension)
1106  out << accessor.level() << '.' << accessor.index();
1107  else
1108  out << accessor.index();
1109 }
1110 
1111 
1112 
1113 template <typename Accessor>
1114 inline std::size_t
1116 {
1117  return sizeof(TriaRawIterator<Accessor>);
1118 }
1119 
1120 
1121 
1122 template <typename Accessor>
1123 template <typename OtherAccessor>
1125  const TriaIterator<OtherAccessor> &i)
1126  : TriaRawIterator<Accessor>(i.accessor)
1127 {}
1128 
1129 
1130 
1131 template <typename Accessor>
1132 template <typename OtherAccessor>
1135  : TriaRawIterator<Accessor>(i.accessor)
1136 {}
1137 
1138 
1139 
1140 template <typename Accessor>
1141 template <typename OtherAccessor>
1144  : TriaRawIterator<Accessor>(i.accessor)
1145 {
1146 #ifdef DEBUG
1147  // do this like this, because:
1148  // if we write
1149  // "Assert (IteratorState::past_the_end || used)"
1150  // used() is called anyway, even if
1151  // state==IteratorState::past_the_end, and will then
1152  // throw the exception!
1153  if (this->state() != IteratorState::past_the_end)
1154  Assert(this->accessor.used(), ExcAssignmentOfUnusedObject());
1155 #endif
1156 }
1157 
1158 template <typename Accessor>
1159 template <typename OtherAccessor>
1161  : TriaRawIterator<Accessor>(a)
1162 {
1163 #ifdef DEBUG
1164  // do this like this, because:
1165  // if we write
1166  // "Assert (IteratorState::past_the_end || used)"
1167  // used() is called anyway, even if
1168  // state==IteratorState::past_the_end, and will then
1169  // throw the exception!
1170  if (this->state() != IteratorState::past_the_end)
1171  Assert(this->accessor.used(), ExcAssignmentOfUnusedObject());
1172 #endif
1173 }
1174 
1175 template <typename Accessor>
1176 template <typename OtherAccessor>
1179  : TriaIterator<Accessor>(i.accessor)
1180 {}
1181 
1182 
1183 
1184 template <typename Accessor>
1185 template <typename OtherAccessor>
1188  : TriaIterator<Accessor>(i)
1189 {
1190 #ifdef DEBUG
1191  // do this like this, because:
1192  // if we write
1193  // "Assert (IteratorState::past_the_end || !has_children())"
1194  // has_children() is called anyway, even if
1195  // state==IteratorState::past_the_end, and will then
1196  // throw the exception!
1197  if (this->state() != IteratorState::past_the_end)
1198  Assert(this->accessor.has_children() == false,
1200 #endif
1201 }
1202 
1203 
1204 
1210 template <typename Accessor>
1211 inline std::ostream &
1212 operator<<(std::ostream &out, const TriaRawIterator<Accessor> &i)
1213 {
1214  i.print(out);
1215  return out;
1216 }
1217 
1218 
1219 
1225 template <typename Accessor>
1226 inline std::ostream &
1227 operator<<(std::ostream &out, const TriaIterator<Accessor> &i)
1228 {
1229  i.print(out);
1230  return out;
1231 }
1232 
1233 
1234 
1240 template <typename Accessor>
1241 inline std::ostream &
1242 operator<<(std::ostream &out, const TriaActiveIterator<Accessor> &i)
1243 {
1244  i.print(out);
1245  return out;
1246 }
1247 
1248 
1250 
1251 
1252 // if in optimized mode: include more templates
1253 #ifndef DEBUG
1254 # include "tria_iterator.templates.h"
1255 #endif
1256 
1257 #endif
OutputOperator< VectorType > & operator<<(OutputOperator< VectorType > &out, unsigned int step)
Definition: operator.h:165
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
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
TriaRawIterator(const TriaRawIterator &)
Accessor * pointer
IteratorState::IteratorStates state() const
Accessor operator*() const
std::enable_if_t< std::is_convertible_v< OtherAccessor, Accessor >, bool > operator==(const TriaRawIterator< OtherAccessor > &) 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:477
#define DEAL_II_CXX20_REQUIRES(condition)
Definition: config.h:166
#define DEAL_II_NAMESPACE_CLOSE
Definition: config.h:478
unsigned int level
Definition: grid_out.cc:4617
#define DeclException0(Exception0)
Definition: exceptions.h:472
#define Assert(cond, exc)
Definition: exceptions.h:1631
static ::ExceptionBase & ExcAdvanceInvalidObject()
static ::ExceptionBase & ExcAssignmentOfUnusedObject()
static ::ExceptionBase & ExcDereferenceInvalidObject(AccessorType arg1)
static ::ExceptionBase & ExcDereferenceInvalidCell(Accessor arg1)
#define DeclException1(Exception1, type1, outsequence)
Definition: exceptions.h:517
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.