Reference documentation for deal.II version 9.1.1
\(\newcommand{\dealcoloneq}{\mathrel{\vcenter{:}}=}\)
tria_iterator.h
1 // ---------------------------------------------------------------------
2 //
3 // Copyright (C) 1998 - 2018 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 
28 # include <deal.II/grid/tria_iterator_base.h>
29 
30 # include <iterator>
31 # include <ostream>
32 
33 DEAL_II_NAMESPACE_OPEN
34 
35 template <int dim, int 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 
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 
228 template <typename Accessor>
229 class TriaRawIterator
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  bool
380  operator==(const TriaRawIterator &) const;
381 
385  bool
386  operator!=(const TriaRawIterator &) const;
387 
413  bool
414  operator<(const TriaRawIterator &) const;
415 
420  bool
421  operator>(const TriaRawIterator &) const;
422 
433  operator++();
434 
447  operator++(int);
448 
454  operator--();
455 
465  operator--(int);
472  state() const;
473 
478  template <class StreamType>
479  void
480  print(StreamType &out) const;
481 
482 
487  std::size_t
488  memory_consumption() const;
489 
495  using iterator_category = std::bidirectional_iterator_tag;
496  using value_type = Accessor;
497  using difference_type = int;
498  using pointer = Accessor *;
499  using reference = Accessor &;
500 
509  Accessor,
510  << "You tried to dereference a cell iterator for which this "
511  << "is not possible. More information on this iterator: "
512  << "level=" << arg1.level() << ", index=" << arg1.index()
513  << ", state="
514  << (arg1.state() == IteratorState::valid ?
515  "valid" :
516  (arg1.state() == IteratorState::past_the_end ?
517  "past_the_end" :
518  "invalid")));
519 
524  Accessor,
525  << "You tried to dereference an iterator for which this "
526  << "is not possible. More information on this iterator: "
527  << "index=" << arg1.index() << ", state="
528  << (arg1.state() == IteratorState::valid ?
529  "valid" :
530  (arg1.state() == IteratorState::past_the_end ?
531  "past_the_end" :
532  "invalid")));
533 
542 
544 protected:
548  Accessor accessor;
549 
550 
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 =
736  using value_type = typename TriaRawIterator<Accessor>::value_type;
737  using pointer = typename TriaRawIterator<Accessor>::pointer;
738  using reference = typename TriaRawIterator<Accessor>::reference;
739  using difference_type = typename TriaRawIterator<Accessor>::difference_type;
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 = 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);
936  using value_type = typename TriaIterator<Accessor>::value_type;
937  using pointer = typename TriaIterator<Accessor>::pointer;
938  using reference = typename TriaIterator<Accessor>::reference;
939  using difference_type = typename TriaIterator<Accessor>::difference_type;
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 &TriaRawIterator<Accessor>::operator*() const
995 {
996  Assert(Accessor::structure_dimension != Accessor::dimension ||
997  state() == IteratorState::valid,
998  ExcDereferenceInvalidCell(accessor));
999  Assert(Accessor::structure_dimension == Accessor::dimension ||
1000  state() == IteratorState::valid,
1001  ExcDereferenceInvalidObject(accessor));
1002 
1003  return accessor;
1004 }
1005 
1006 
1007 
1008 template <typename Accessor>
1010 {
1011  Assert(Accessor::structure_dimension != Accessor::dimension ||
1012  state() == IteratorState::valid,
1013  ExcDereferenceInvalidCell(accessor));
1014  Assert(Accessor::structure_dimension == Accessor::dimension ||
1015  state() == IteratorState::valid,
1016  ExcDereferenceInvalidObject(accessor));
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 {
1062  Assert(state() != IteratorState::invalid,
1063  ExcDereferenceInvalidObject(accessor));
1064  Assert(other.state() != IteratorState::invalid,
1066 
1067  Assert(&accessor.get_triangulation() == &other.accessor.get_triangulation(),
1068  ExcInvalidComparison());
1069 
1070  // Deal with iterators past end
1071  if (state() == IteratorState::past_the_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 {
1095  Assert(state() == IteratorState::valid, ExcAdvanceInvalidObject());
1096 
1097  ++accessor;
1098  return *this;
1099 }
1100 
1101 
1102 
1103 template <typename Accessor>
1106 {
1107  Assert(state() == IteratorState::valid, ExcAdvanceInvalidObject());
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 
1227 template <typename Accessor>
1228 inline std::ostream &
1229 operator<<(std::ostream &out, const TriaRawIterator<Accessor> &i)
1230 {
1231  i.print(out);
1232  return out;
1233 }
1234 
1235 
1236 
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 
1261 template <typename Accessor>
1262 inline std::ostream &
1263 operator<<(std::ostream &out, const TriaActiveIterator<Accessor> &i)
1264 {
1265  i.print(out);
1266  return out;
1267 }
1268 
1269 
1270 DEAL_II_NAMESPACE_CLOSE
1271 
1272 
1273 // if in optimized mode: include more templates
1274 # ifndef DEBUG
1275 # include "tria_iterator.templates.h"
1276 # endif
1277 
1278 
1279 /*---------------------------- tria-iterator.h ---------------------------*/
1280 #endif
1281 /*---------------------------- tria-iterator.h ---------------------------*/
Iterator is invalid, probably due to an error.
TriaActiveIterator< Accessor > & operator++()
const Accessor * operator->() const
static ::ExceptionBase & ExcInvalidComparison()
static ::ExceptionBase & ExcAdvanceInvalidObject()
static ::ExceptionBase & ExcDereferenceInvalidObject(AccessorType arg1)
const Accessor & operator*() const
static ::ExceptionBase & ExcAssignmentOfInactiveObject()
bool operator>(const TriaRawIterator &) const
TriaIterator< Accessor > & operator++()
typename TriaRawIterator< Accessor >::iterator_category iterator_category
#define DeclException1(Exception1, type1, outsequence)
Definition: exceptions.h:518
Accessor AccessorType
TriaActiveIterator< Accessor > & operator--()
#define Assert(cond, exc)
Definition: exceptions.h:1407
TriaRawIterator & operator++()
#define DeclException0(Exception0)
Definition: exceptions.h:473
TriaIterator< Accessor > & operator--()
static ::ExceptionBase & ExcDereferenceInvalidObject(Accessor arg1)
bool operator==(const TriaRawIterator &) const
bool operator!=(const TriaRawIterator &) const
TriaRawIterator & operator--()
static ::ExceptionBase & ExcAssignmentOfUnusedObject()
TriaActiveIterator< Accessor > & operator=(const TriaActiveIterator< Accessor > &)
static ::ExceptionBase & ExcDereferenceInvalidCell(Accessor arg1)
TriaRawIterator & operator=(const TriaRawIterator &)
Iterator reached end of container.
const Accessor & access_any() const
Iterator points to a valid object.
TriaIterator< Accessor > & operator=(const TriaIterator< Accessor > &)
void print(StreamType &out) const
IteratorState::IteratorStates state() const
std::bidirectional_iterator_tag iterator_category
bool operator<(const TriaRawIterator &) const
std::size_t memory_consumption() const
Point< dim, typename ProductType< Number, typename EnableIfScalar< OtherNumber >::type >::type > operator*(const OtherNumber) const