Reference documentation for deal.II version Git 71165045b9 2021-01-23 20:21:06 -0500
\(\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 - 2019 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 &operator*() const;
336 
340  Accessor &operator*();
341 
348  const Accessor *operator->() const;
349 
353  Accessor *operator->();
354 
355 
365  const Accessor &
366  access_any() const;
367 
374  operator=(const TriaRawIterator &);
375 
379  template <typename OtherAccessor = Accessor>
380  typename std::enable_if<std::is_convertible<OtherAccessor, Accessor>::value,
381  bool>::type
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 
449  operator++(int);
450 
456  operator--();
457 
467  operator--(int);
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;
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:
584  TriaIterator();
585 
590 
601 
611  TriaIterator(
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 
701  operator++();
702 
713  operator++(int);
714 
720  operator--();
721 
726  operator--(int);
734  using iterator_category =
740 
744  DeclException0(ExcAssignmentOfUnusedObject);
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 = 0);
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 
898  operator++();
899 
914  operator++(int);
915 
921  operator--();
922 
927  operator--(int);
940 
944  DeclException0(ExcAssignmentOfInactiveObject);
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 &TriaRawIterator<Accessor>::operator*() const
995 {
996  Assert(Accessor::structure_dimension != Accessor::dimension ||
999  Assert(Accessor::structure_dimension == Accessor::dimension ||
1002 
1003  return accessor;
1004 }
1005 
1006 
1007 
1008 template <typename Accessor>
1010 {
1011  Assert(Accessor::structure_dimension != Accessor::dimension ||
1014  Assert(Accessor::structure_dimension == Accessor::dimension ||
1017 
1018  return accessor;
1019 }
1020 
1021 
1022 
1023 template <typename Accessor>
1024 inline const Accessor &
1026 {
1027  return accessor;
1028 }
1029 
1030 
1031 
1032 template <typename Accessor>
1033 inline const Accessor *TriaRawIterator<Accessor>::operator->() const
1034 {
1035  return &(this->operator*());
1036 }
1037 
1038 
1039 
1040 template <typename Accessor>
1042 {
1043  return &(this->operator*());
1044 }
1045 
1046 
1047 
1048 template <typename Accessor>
1051 {
1052  return accessor.state();
1053 }
1054 
1055 
1056 
1057 template <typename Accessor>
1058 inline bool
1061 {
1064  Assert(other.state() != IteratorState::invalid,
1066 
1067  Assert(&accessor.get_triangulation() == &other.accessor.get_triangulation(),
1069 
1070  // Deal with iterators past end
1072  return false;
1073  if (other.state() == IteratorState::past_the_end)
1074  return true;
1075 
1076  return ((**this) < (*other));
1077 }
1078 
1079 
1080 
1081 template <typename Accessor>
1082 inline bool
1085 {
1086  return (other < *this);
1087 }
1088 
1089 
1090 
1091 template <typename Accessor>
1094 {
1096 
1097  ++accessor;
1098  return *this;
1099 }
1100 
1101 
1102 
1103 template <typename Accessor>
1106 {
1108 
1109  --accessor;
1110  return *this;
1111 }
1112 
1113 
1114 
1115 template <typename Accessor>
1116 template <class StreamType>
1117 inline void
1118 TriaRawIterator<Accessor>::print(StreamType &out) const
1119 {
1120  if (Accessor::structure_dimension == Accessor::dimension)
1121  out << accessor.level() << "." << accessor.index();
1122  else
1123  out << accessor.index();
1124 }
1125 
1126 
1127 
1128 template <typename Accessor>
1129 inline std::size_t
1131 {
1132  return sizeof(TriaRawIterator<Accessor>);
1133 }
1134 
1135 
1136 
1137 template <typename Accessor>
1138 template <typename OtherAccessor>
1140  const TriaIterator<OtherAccessor> &i)
1141  : TriaRawIterator<Accessor>(i.accessor)
1142 {}
1143 
1144 
1145 
1146 template <typename Accessor>
1147 template <typename OtherAccessor>
1150  : TriaRawIterator<Accessor>(i.accessor)
1151 {}
1152 
1153 
1154 
1155 template <typename Accessor>
1156 template <typename OtherAccessor>
1159  : TriaRawIterator<Accessor>(i.accessor)
1160 {
1161 # ifdef DEBUG
1162  // do this like this, because:
1163  // if we write
1164  // "Assert (IteratorState::past_the_end || used)"
1165  // used() is called anyway, even if
1166  // state==IteratorState::past_the_end, and will then
1167  // throw the exception!
1168  if (this->state() != IteratorState::past_the_end)
1169  Assert(this->accessor.used(), ExcAssignmentOfUnusedObject());
1170 # endif
1171 }
1172 
1173 template <typename Accessor>
1174 template <typename OtherAccessor>
1176  : TriaRawIterator<Accessor>(a)
1177 {
1178 # ifdef DEBUG
1179  // do this like this, because:
1180  // if we write
1181  // "Assert (IteratorState::past_the_end || used)"
1182  // used() is called anyway, even if
1183  // state==IteratorState::past_the_end, and will then
1184  // throw the exception!
1185  if (this->state() != IteratorState::past_the_end)
1186  Assert(this->accessor.used(), ExcAssignmentOfUnusedObject());
1187 # endif
1188 }
1189 
1190 template <typename Accessor>
1191 template <typename OtherAccessor>
1194  : TriaIterator<Accessor>(i.accessor)
1195 {}
1196 
1197 
1198 
1199 template <typename Accessor>
1200 template <typename OtherAccessor>
1203  : TriaIterator<Accessor>(i)
1204 {
1205 # ifdef DEBUG
1206  // do this like this, because:
1207  // if we write
1208  // "Assert (IteratorState::past_the_end || !has_children())"
1209  // has_children() is called anyway, even if
1210  // state==IteratorState::past_the_end, and will then
1211  // throw the exception!
1212  if (this->state() != IteratorState::past_the_end)
1213  Assert(this->accessor.has_children() == false,
1215 # endif
1216 }
1217 
1218 
1219 
1225 template <typename Accessor>
1226 inline std::ostream &
1227 operator<<(std::ostream &out, const TriaRawIterator<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 TriaIterator<Accessor> &i)
1243 {
1244  i.print(out);
1245  return out;
1246 }
1247 
1248 
1249 
1255 template <typename Accessor>
1256 inline std::ostream &
1257 operator<<(std::ostream &out, const TriaActiveIterator<Accessor> &i)
1258 {
1259  i.print(out);
1260  return out;
1261 }
1262 
1263 
1265 
1266 
1267 // if in optimized mode: include more templates
1268 # ifndef DEBUG
1269 # include "tria_iterator.templates.h"
1270 # endif
1271 
1272 
1273 /*---------------------------- tria-iterator.h ---------------------------*/
1274 #endif
1275 /*---------------------------- 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:515
Accessor AccessorType
typename TriaRawIterator< Accessor >::pointer pointer
#define Assert(cond, exc)
Definition: exceptions.h:1466
Accessor & reference
TriaRawIterator & operator++()
#define DeclException0(Exception0)
Definition: exceptions.h:470
Accessor * pointer
#define DEAL_II_NAMESPACE_CLOSE
Definition: config.h:380
unsigned int level
Definition: grid_out.cc:4370
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:379
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