Reference documentation for deal.II version Git 34859fde61 2019-12-10 11:26:22 -0700
\(\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 // 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 
231 template <typename Accessor>
233 {
234 public:
240  using AccessorType = Accessor;
241 
246  TriaRawIterator();
247 
252 
265  explicit TriaRawIterator(const Accessor &a);
266 
271  template <typename OtherAccessor>
272  explicit TriaRawIterator(const OtherAccessor &a);
273 
281  const int level,
282  const int index,
283  const typename AccessorType::AccessorData *local_data = nullptr);
284 
294  template <typename OtherAccessor>
296 
303  const TriaAccessorBase<Accessor::structure_dimension,
304  Accessor::dimension,
305  Accessor::space_dimension> &tria_accessor,
306  const typename Accessor::AccessorData * local_data);
307 
312  template <typename OtherAccessor>
314 
319  template <typename OtherAccessor>
321 
338  const Accessor &operator*() const;
339 
343  Accessor &operator*();
344 
351  const Accessor *operator->() const;
352 
356  Accessor *operator->();
357 
358 
368  const Accessor &
369  access_any() const;
370 
377  operator=(const TriaRawIterator &);
378 
382  bool
383  operator==(const TriaRawIterator &) const;
384 
388  bool
389  operator!=(const TriaRawIterator &) const;
390 
416  bool
417  operator<(const TriaRawIterator &) const;
418 
423  bool
424  operator>(const TriaRawIterator &) const;
425 
436  operator++();
437 
450  operator++(int);
451 
457  operator--();
458 
468  operator--(int);
475  state() const;
476 
481  template <class StreamType>
482  void
483  print(StreamType &out) const;
484 
485 
490  std::size_t
491  memory_consumption() const;
492 
498  using iterator_category = std::bidirectional_iterator_tag;
499  using value_type = Accessor;
500  using difference_type = int;
501  using pointer = Accessor *;
502  using reference = Accessor &;
503 
512  Accessor,
513  << "You tried to dereference a cell iterator for which this "
514  << "is not possible. More information on this iterator: "
515  << "level=" << arg1.level() << ", index=" << arg1.index()
516  << ", state="
517  << (arg1.state() == IteratorState::valid ?
518  "valid" :
519  (arg1.state() == IteratorState::past_the_end ?
520  "past_the_end" :
521  "invalid")));
522 
527  Accessor,
528  << "You tried to dereference an iterator for which this "
529  << "is not possible. More information on this iterator: "
530  << "index=" << arg1.index() << ", state="
531  << (arg1.state() == IteratorState::valid ?
532  "valid" :
533  (arg1.state() == IteratorState::past_the_end ?
534  "past_the_end" :
535  "invalid")));
536 
545 
547 protected:
551  Accessor accessor;
552 
553 
554  // Make all other iterator class templates friends of this class. This is
555  // necessary for the implementation of conversion constructors.
556  //
557  // In fact, we would not need them to be friends if they were for different
558  // dimensions, but the compiler dislikes giving a fixed dimension and
559  // variable accessor since then it says that would be a partial
560  // specialization.
561  template <typename SomeAccessor>
562  friend class TriaRawIterator;
563  template <typename SomeAccessor>
564  friend class TriaIterator;
565  template <typename SomeAccessor>
566  friend class TriaActiveIterator;
567 };
568 
569 
577 template <typename Accessor>
578 class TriaIterator : public TriaRawIterator<Accessor>
579 {
580 public:
585  TriaIterator();
586 
591 
602 
612  TriaIterator(
614  const int level,
615  const int index,
616  const typename Accessor::AccessorData *local_data = nullptr);
617 
622  template <typename OtherAccessor>
623  explicit TriaIterator(const OtherAccessor &a);
624 
634  template <typename OtherAccessor>
636 
642  TriaIterator(const TriaAccessorBase<Accessor::structure_dimension,
643  Accessor::dimension,
644  Accessor::space_dimension> &tria_accessor,
645  const typename Accessor::AccessorData * local_data);
646 
652  template <typename OtherAccessor>
654 
659  template <typename OtherAccessor>
661 
667 
674 
679  template <class OtherAccessor>
682 
688  template <class OtherAccessor>
691 
702  operator++();
703 
714  operator++(int);
715 
721  operator--();
722 
727  operator--(int);
735  using iterator_category =
737  using value_type = typename TriaRawIterator<Accessor>::value_type;
738  using pointer = typename TriaRawIterator<Accessor>::pointer;
739  using reference = typename TriaRawIterator<Accessor>::reference;
740  using difference_type = typename TriaRawIterator<Accessor>::difference_type;
741 
745  DeclException0(ExcAssignmentOfUnusedObject);
746 };
747 
748 
758 template <typename Accessor>
759 class TriaActiveIterator : public TriaIterator<Accessor>
760 {
761 public:
767 
772 
783 
794 
806  const int level,
807  const int index,
808  const typename Accessor::AccessorData *local_data = 0);
809 
819  template <typename OtherAccessor>
821 
828  const TriaAccessorBase<Accessor::structure_dimension,
829  Accessor::dimension,
830  Accessor::space_dimension> &tria_accessor,
831  const typename Accessor::AccessorData * local_data);
832 
844  template <typename OtherAccessor>
846 
852 
859 
866 
871  template <class OtherAccessor>
874 
880  template <class OtherAccessor>
883 
889  template <class OtherAccessor>
892 
899  operator++();
900 
915  operator++(int);
916 
922  operator--();
923 
928  operator--(int);
937  using value_type = typename TriaIterator<Accessor>::value_type;
938  using pointer = typename TriaIterator<Accessor>::pointer;
939  using reference = typename TriaIterator<Accessor>::reference;
940  using difference_type = typename TriaIterator<Accessor>::difference_type;
941 
945  DeclException0(ExcAssignmentOfInactiveObject);
946 };
947 
948 
949 /*----------------------- Inline functions -------------------*/
950 
951 
952 template <typename Accessor>
954  : accessor(a)
955 {}
956 
957 
958 
959 template <typename Accessor>
960 template <typename OtherAccessor>
961 inline TriaRawIterator<Accessor>::TriaRawIterator(const OtherAccessor &a)
962  : accessor(a)
963 {}
964 
965 
966 
967 template <typename Accessor>
968 template <typename OtherAccessor>
971  : accessor(i.accessor)
972 {}
973 
974 
975 
976 template <typename Accessor>
977 template <typename OtherAccessor>
980  : accessor(i.accessor)
981 {}
982 
983 
984 
985 template <typename Accessor>
986 template <typename OtherAccessor>
989  : accessor(i.accessor)
990 {}
991 
992 
993 
994 template <typename Accessor>
995 inline const Accessor &TriaRawIterator<Accessor>::operator*() const
996 {
997  Assert(Accessor::structure_dimension != Accessor::dimension ||
1000  Assert(Accessor::structure_dimension == Accessor::dimension ||
1003 
1004  return accessor;
1005 }
1006 
1007 
1008 
1009 template <typename Accessor>
1011 {
1012  Assert(Accessor::structure_dimension != Accessor::dimension ||
1015  Assert(Accessor::structure_dimension == Accessor::dimension ||
1018 
1019  return accessor;
1020 }
1021 
1022 
1023 
1024 template <typename Accessor>
1025 inline const Accessor &
1027 {
1028  return accessor;
1029 }
1030 
1031 
1032 
1033 template <typename Accessor>
1034 inline const Accessor *TriaRawIterator<Accessor>::operator->() const
1035 {
1036  return &(this->operator*());
1037 }
1038 
1039 
1040 
1041 template <typename Accessor>
1043 {
1044  return &(this->operator*());
1045 }
1046 
1047 
1048 
1049 template <typename Accessor>
1052 {
1053  return accessor.state();
1054 }
1055 
1056 
1057 
1058 template <typename Accessor>
1059 inline bool
1062 {
1065  Assert(other.state() != IteratorState::invalid,
1067 
1068  Assert(&accessor.get_triangulation() == &other.accessor.get_triangulation(),
1070 
1071  // Deal with iterators past end
1073  return false;
1074  if (other.state() == IteratorState::past_the_end)
1075  return true;
1076 
1077  return ((**this) < (*other));
1078 }
1079 
1080 
1081 
1082 template <typename Accessor>
1083 inline bool
1086 {
1087  return (other < *this);
1088 }
1089 
1090 
1091 
1092 template <typename Accessor>
1095 {
1097 
1098  ++accessor;
1099  return *this;
1100 }
1101 
1102 
1103 
1104 template <typename Accessor>
1107 {
1109 
1110  --accessor;
1111  return *this;
1112 }
1113 
1114 
1115 
1116 template <typename Accessor>
1117 template <class StreamType>
1118 inline void
1119 TriaRawIterator<Accessor>::print(StreamType &out) const
1120 {
1121  if (Accessor::structure_dimension == Accessor::dimension)
1122  out << accessor.level() << "." << accessor.index();
1123  else
1124  out << accessor.index();
1125 }
1126 
1127 
1128 
1129 template <typename Accessor>
1130 inline std::size_t
1132 {
1133  return sizeof(TriaRawIterator<Accessor>);
1134 }
1135 
1136 
1137 
1138 template <typename Accessor>
1139 template <typename OtherAccessor>
1141  const TriaIterator<OtherAccessor> &i)
1142  : TriaRawIterator<Accessor>(i.accessor)
1143 {}
1144 
1145 
1146 
1147 template <typename Accessor>
1148 template <typename OtherAccessor>
1151  : TriaRawIterator<Accessor>(i.accessor)
1152 {}
1153 
1154 
1155 
1156 template <typename Accessor>
1157 template <typename OtherAccessor>
1160  : TriaRawIterator<Accessor>(i.accessor)
1161 {
1162 # ifdef DEBUG
1163  // do this like this, because:
1164  // if we write
1165  // "Assert (IteratorState::past_the_end || used)"
1166  // used() is called anyway, even if
1167  // state==IteratorState::past_the_end, and will then
1168  // throw the exception!
1169  if (this->state() != IteratorState::past_the_end)
1170  Assert(this->accessor.used(), ExcAssignmentOfUnusedObject());
1171 # endif
1172 }
1173 
1174 template <typename Accessor>
1175 template <typename OtherAccessor>
1177  : TriaRawIterator<Accessor>(a)
1178 {
1179 # ifdef DEBUG
1180  // do this like this, because:
1181  // if we write
1182  // "Assert (IteratorState::past_the_end || used)"
1183  // used() is called anyway, even if
1184  // state==IteratorState::past_the_end, and will then
1185  // throw the exception!
1186  if (this->state() != IteratorState::past_the_end)
1187  Assert(this->accessor.used(), ExcAssignmentOfUnusedObject());
1188 # endif
1189 }
1190 
1191 template <typename Accessor>
1192 template <typename OtherAccessor>
1195  : TriaIterator<Accessor>(i.accessor)
1196 {}
1197 
1198 
1199 
1200 template <typename Accessor>
1201 template <typename OtherAccessor>
1204  : TriaIterator<Accessor>(i)
1205 {
1206 # ifdef DEBUG
1207  // do this like this, because:
1208  // if we write
1209  // "Assert (IteratorState::past_the_end || !has_children())"
1210  // has_children() is called anyway, even if
1211  // state==IteratorState::past_the_end, and will then
1212  // throw the exception!
1213  if (this->state() != IteratorState::past_the_end)
1214  Assert(this->accessor.has_children() == false,
1216 # endif
1217 }
1218 
1219 
1220 
1228 template <typename Accessor>
1229 inline std::ostream &
1230 operator<<(std::ostream &out, const TriaRawIterator<Accessor> &i)
1231 {
1232  i.print(out);
1233  return out;
1234 }
1235 
1236 
1237 
1245 template <typename Accessor>
1246 inline std::ostream &
1247 operator<<(std::ostream &out, const TriaIterator<Accessor> &i)
1248 {
1249  i.print(out);
1250  return out;
1251 }
1252 
1253 
1254 
1262 template <typename Accessor>
1263 inline std::ostream &
1264 operator<<(std::ostream &out, const TriaActiveIterator<Accessor> &i)
1265 {
1266  i.print(out);
1267  return out;
1268 }
1269 
1270 
1271 DEAL_II_NAMESPACE_CLOSE
1272 
1273 
1274 // if in optimized mode: include more templates
1275 # ifndef DEBUG
1276 # include "tria_iterator.templates.h"
1277 # endif
1278 
1279 
1280 /*---------------------------- tria-iterator.h ---------------------------*/
1281 #endif
1282 /*---------------------------- tria-iterator.h ---------------------------*/
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
typename TriaRawIterator< Accessor >::iterator_category iterator_category
#define DeclException1(Exception1, type1, outsequence)
Definition: exceptions.h:518
Accessor AccessorType
#define Assert(cond, exc)
Definition: exceptions.h:1411
TriaRawIterator & operator++()
#define DeclException0(Exception0)
Definition: exceptions.h:473
static ::ExceptionBase & ExcDereferenceInvalidObject(Accessor arg1)
bool operator==(const TriaRawIterator &) const
bool operator!=(const TriaRawIterator &) const
TriaRawIterator & operator--()
static ::ExceptionBase & ExcAssignmentOfUnusedObject()
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.
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