Reference documentation for deal.II version 8.1.0
tria_iterator.h
1 // ---------------------------------------------------------------------
2 // @f$Id: tria_iterator.h 30040 2013-07-18 17:06:48Z maier @f$
3 //
4 // Copyright (C) 1998 - 2013 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // The deal.II library is free software; you can use it, redistribute
9 // it, and/or modify it under the terms of the GNU Lesser General
10 // Public License as published by the Free Software Foundation; either
11 // version 2.1 of the License, or (at your option) any later version.
12 // The full text of the license can be found in the file LICENSE at
13 // the top level of the deal.II distribution.
14 //
15 // ---------------------------------------------------------------------
16 
17 #ifndef __deal2__tria_iterator_h
18 #define __deal2__tria_iterator_h
19 
20 
21 /*---------------------------- tria-iterator.h ---------------------------*/
22 
23 
24 #include <deal.II/base/config.h>
26 
27 #include <deal.II/base/point.h>
28 #include <deal.II/grid/tria_iterator_base.h>
29 
30 #include <iterator>
31 
32 #include <ostream>
33 
35 
36 template <int dim, int spacedim> class Triangulation;
37 template <int, int, int> class TriaAccessorBase;
38 
39 template <typename> class TriaRawIterator;
40 template <typename> class TriaIterator;
41 template <typename> class TriaActiveIterator;
42 
43 
44 
45 // note: in non-debug mode, i.e. with optimizations, the file
46 // tria_iterator.templates.h is included at the end of this file.
47 // this includes a lot of templates and thus makes compilation
48 // slower, but at the same time allows for more aggressive
49 // inlining and thus faster code.
50 
51 
232 template <typename Accessor>
233 class TriaRawIterator : public std::iterator<std::bidirectional_iterator_tag,Accessor>
234 {
235 public:
243  typedef Accessor AccessorType;
244 
249  TriaRawIterator ();
250 
255 
272  explicit TriaRawIterator (const Accessor &a);
273 
280  template <typename OtherAccessor>
281  explicit TriaRawIterator (const OtherAccessor &a);
282 
292  const int level,
293  const int index,
294  const typename AccessorType::AccessorData *local_data = 0);
295 
311  template <typename OtherAccessor>
313 
324  const typename Accessor::AccessorData *local_data);
325 
333  template <typename OtherAccessor>
335 
343  template <typename OtherAccessor>
345 
366  const Accessor &operator * () const;
367 
372  Accessor &operator * ();
373 
382  const Accessor *operator -> () const;
383 
388  Accessor *operator -> ();
389 
390 
406  const Accessor &access_any () const;
407 
414 
418 // template <class OtherAccessor>
419 // TriaRawIterator & operator = (const TriaRawIterator<OtherAccessor>&);
420 
424 // template <class OtherAccessor>
425 // TriaRawIterator & operator = (const TriaIterator<OtherAccessor>&);
426 
430 // template <class OtherAccessor>
431 // TriaRawIterator & operator = (const TriaActiveIterator<OtherAccessor>&);
432 
436  bool operator == (const TriaRawIterator &) const;
437 
441  bool operator != (const TriaRawIterator &) const;
442 
475  bool operator < (const TriaRawIterator &) const;
476 
494 
513 
529 
554 
560  template <class STREAM>
561  void print (STREAM &out) const;
562 
563 
569  std::size_t memory_consumption () const;
570 
571 
578  DeclException1 (ExcDereferenceInvalidCell,
579  Accessor,
580  << "You tried to dereference a cell iterator for which this "
581  << "is not possible. More information on this iterator: "
582  << "level=" << arg1.level()
583  << ", index=" << arg1.index()
584  << ", state="
585  << (arg1.state() == IteratorState::valid ? "valid" :
586  (arg1.state() == IteratorState::past_the_end ?
587  "past_the_end" : "invalid")));
588 
595  DeclException1 (ExcDereferenceInvalidObject,
596  Accessor,
597  << "You tried to dereference an iterator for which this "
598  << "is not possible. More information on this iterator: "
599  << "index=" << arg1.index()
600  << ", state="
601  << (arg1.state() == IteratorState::valid ? "valid" :
602  (arg1.state() == IteratorState::past_the_end ?
603  "past_the_end" : "invalid")));
604 
608  DeclException0 (ExcAdvanceInvalidObject);
612  DeclException0 (ExcInvalidComparison);
613 
615 protected:
619  Accessor accessor;
620 
621 
635  template <typename SomeAccessor> friend class TriaRawIterator;
636  template <typename SomeAccessor> friend class TriaIterator;
637  template <typename SomeAccessor> friend class TriaActiveIterator;
638 };
639 
640 
648 template <typename Accessor>
649 class TriaIterator : public TriaRawIterator<Accessor>
650 {
651 public:
656  TriaIterator ();
657 
662 
674 
689  const int level,
690  const int index,
691  const typename Accessor::AccessorData *local_data = 0);
692 
697  template <typename OtherAccessor>
698  explicit TriaIterator (const OtherAccessor &a);
699 
715  template <typename OtherAccessor>
717 
728  const typename Accessor::AccessorData *local_data);
729 
736  template <typename OtherAccessor>
738 
745  template <typename OtherAccessor>
747 
753 
762 
769  template <class OtherAccessor>
772 
781  template <class OtherAccessor>
784 
794 
813 
821 
831  DeclException0 (ExcAssignmentOfUnusedObject);
832 };
833 
834 
844 template <typename Accessor>
845 class TriaActiveIterator : public TriaIterator<Accessor>
846 {
847 public:
853 
858 
870 
882 
897  const int level,
898  const int index,
899  const typename Accessor::AccessorData *local_data = 0);
900 
916  template <typename OtherAccessor>
918 
929  const typename Accessor::AccessorData *local_data);
930 
941  template <typename OtherAccessor>
943 
949 
958 
967 
973  template <class OtherAccessor>
976 
985  template <class OtherAccessor>
988 
997  template <class OtherAccessor>
1000 
1008 
1029 
1037 
1047  DeclException0 (ExcAssignmentOfInactiveObject);
1048 };
1049 
1050 
1051 /*----------------------- Inline functions -------------------*/
1052 
1053 
1054 template <typename Accessor>
1055 inline
1057 TriaRawIterator (const Accessor &a)
1058  :
1059  accessor (a)
1060 {}
1061 
1062 
1063 
1064 template <typename Accessor>
1065 template <typename OtherAccessor>
1066 inline
1068 TriaRawIterator (const OtherAccessor &a)
1069  :
1070  accessor (a)
1071 {}
1072 
1073 
1074 
1075 template <typename Accessor>
1076 template <typename OtherAccessor>
1077 inline
1080  :
1081  accessor (i.accessor)
1082 {}
1083 
1084 
1085 
1086 template <typename Accessor>
1087 template <typename OtherAccessor>
1088 inline
1091  :
1092  accessor (i.accessor)
1093 {}
1094 
1095 
1096 
1097 template <typename Accessor>
1098 template <typename OtherAccessor>
1099 inline
1102  :
1103  accessor (i.accessor)
1104 {}
1105 
1106 
1107 
1108 template <typename Accessor>
1109 inline
1110 const Accessor &
1112 {
1113  Assert (Accessor::structure_dimension!=Accessor::dimension ||
1114  state() == IteratorState::valid,
1115  ExcDereferenceInvalidCell(accessor));
1116  Assert (Accessor::structure_dimension==Accessor::dimension ||
1117  state() == IteratorState::valid,
1118  ExcDereferenceInvalidObject(accessor));
1119 
1120  return accessor;
1121 }
1122 
1123 
1124 
1125 template <typename Accessor>
1126 inline
1127 Accessor &
1129 {
1130  Assert (Accessor::structure_dimension!=Accessor::dimension ||
1131  state() == IteratorState::valid,
1132  ExcDereferenceInvalidCell(accessor));
1133  Assert (Accessor::structure_dimension==Accessor::dimension ||
1134  state() == IteratorState::valid,
1135  ExcDereferenceInvalidObject(accessor));
1136 
1137  return accessor;
1138 }
1139 
1140 
1141 
1142 template <typename Accessor>
1143 inline
1144 const Accessor &
1146 {
1147  return accessor;
1148 }
1149 
1150 
1151 
1152 template <typename Accessor>
1153 inline
1154 const Accessor *
1156 {
1157  return &(this->operator* ());
1158 }
1159 
1160 
1161 
1162 template <typename Accessor>
1163 inline
1164 Accessor *
1166 {
1167  return &(this->operator* ());
1168 }
1169 
1170 
1171 
1172 template <typename Accessor>
1173 inline
1176 {
1177  return accessor.state ();
1178 }
1179 
1180 
1181 
1182 template <typename Accessor>
1183 inline
1184 bool
1186 {
1187  Assert (state() != IteratorState::invalid, ExcDereferenceInvalidObject(accessor));
1188  Assert (other.state() != IteratorState::invalid, ExcDereferenceInvalidObject(other.accessor));
1189 
1190  Assert (&accessor.get_triangulation() == &other.accessor.get_triangulation(),
1191  ExcInvalidComparison());
1192 
1193  // Deal with iterators past end
1194  if (state()==IteratorState::past_the_end)
1195  return false;
1196  if (other.state()==IteratorState::past_the_end)
1197  return true;
1198 
1199  return ((**this) < (*other));
1200 }
1201 
1202 
1203 template <typename Accessor>
1204 inline
1207 {
1208  Assert (state() == IteratorState::valid, ExcAdvanceInvalidObject());
1209 
1210  ++accessor;
1211  return *this;
1212 }
1213 
1214 
1215 
1216 template <typename Accessor>
1217 inline
1220 {
1221  Assert (state() == IteratorState::valid, ExcAdvanceInvalidObject());
1222 
1223  --accessor;
1224  return *this;
1225 }
1226 
1227 
1228 
1229 template <typename Accessor>
1230 template <class STREAM>
1231 inline
1232 void
1234 {
1235  if (Accessor::structure_dimension==Accessor::dimension)
1236  out << accessor.level() << "." << accessor.index();
1237  else
1238  out << accessor.index();
1239 }
1240 
1241 
1242 
1243 template <typename Accessor>
1244 inline
1245 std::size_t
1247 {
1248  return sizeof(TriaRawIterator<Accessor>);
1249 }
1250 
1251 
1252 
1253 template <typename Accessor>
1254 template <typename OtherAccessor>
1255 inline
1257  :
1258  TriaRawIterator<Accessor> (i.accessor)
1259 {}
1260 
1261 
1262 
1263 template <typename Accessor>
1264 template <typename OtherAccessor>
1265 inline
1267  :
1268  TriaRawIterator<Accessor> (i.accessor)
1269 {}
1270 
1271 
1272 
1273 template <typename Accessor>
1274 template <typename OtherAccessor>
1275 inline
1277  :
1278  TriaRawIterator<Accessor> (i.accessor)
1279 {
1280 #ifdef DEBUG
1281  // do this like this, because:
1282  // if we write
1283  // "Assert (IteratorState::past_the_end || used)"
1284  // used() is called anyway, even if
1285  // state==IteratorState::past_the_end, and will then
1286  // throw the exception!
1287  if (this->state() != IteratorState::past_the_end)
1288  Assert (this->accessor.used(),
1289  ExcAssignmentOfUnusedObject());
1290 #endif
1291 }
1292 
1293 template <typename Accessor>
1294 template <typename OtherAccessor>
1296  :
1297  TriaRawIterator<Accessor> (a)
1298 {
1299 #ifdef DEBUG
1300  // do this like this, because:
1301  // if we write
1302  // "Assert (IteratorState::past_the_end || used)"
1303  // used() is called anyway, even if
1304  // state==IteratorState::past_the_end, and will then
1305  // throw the exception!
1306  if (this->state() != IteratorState::past_the_end)
1307  Assert (this->accessor.used(),
1308  ExcAssignmentOfUnusedObject());
1309 #endif
1310 }
1311 
1312 template <typename Accessor>
1313 template <typename OtherAccessor>
1314 inline
1316  :
1317  TriaIterator<Accessor> (i.accessor)
1318 {}
1319 
1320 
1321 
1322 template <typename Accessor>
1323 template <typename OtherAccessor>
1324 inline
1326  :
1327  TriaIterator<Accessor> (i)
1328 {
1329 #ifdef DEBUG
1330  // do this like this, because:
1331  // if we write
1332  // "Assert (IteratorState::past_the_end || !has_children())"
1333  // has_children() is called anyway, even if
1334  // state==IteratorState::past_the_end, and will then
1335  // throw the exception!
1336  if (this->state() != IteratorState::past_the_end)
1337  Assert (this->accessor.has_children()==false,
1338  ExcAssignmentOfInactiveObject());
1339 #endif
1340 }
1341 
1342 
1343 
1352 template <typename Accessor>
1353 inline
1354 std::ostream &operator << (std::ostream &out,
1355  const TriaRawIterator<Accessor> &i)
1356 {
1357  i.print(out);
1358  return out;
1359 }
1360 
1361 
1362 
1371 template <typename Accessor>
1372 inline
1373 std::ostream &operator << (std::ostream &out,
1374  const TriaIterator<Accessor> &i)
1375 {
1376  i.print(out);
1377  return out;
1378 }
1379 
1380 
1381 
1390 template <typename Accessor>
1391 inline
1392 std::ostream &operator << (std::ostream &out,
1394 {
1395  i.print(out);
1396  return out;
1397 }
1398 
1399 
1400 DEAL_II_NAMESPACE_CLOSE
1401 
1402 
1403 // if in optimized mode: include more templates
1404 #ifndef DEBUG
1405 # include "tria_iterator.templates.h"
1406 #endif
1407 
1408 
1409 /*---------------------------- tria-iterator.h ---------------------------*/
1410 #endif
1411 /*---------------------------- tria-iterator.h ---------------------------*/
Accessor AccessorType
Iterator points to a valid object.
TriaIterator< Accessor > & operator++()
DeclException0(ExcAssignmentOfUnusedObject)
DeclException0(ExcAssignmentOfInactiveObject)
void print(STREAM &out) const
Tensor< 1, dim, Number > operator*(const Tensor< 1, dim, Number > &t, const Number factor)
Definition: tensor_base.h:1361
const Accessor * operator->() const
TriaActiveIterator< Accessor > & operator++()
Iterator reached end of container.
const Accessor & operator*() const
Iterator is invalid, probably due to an error.
std::size_t memory_consumption() const
TriaActiveIterator< Accessor > & operator--()
#define Assert(cond, exc)
Definition: exceptions.h:299
TriaRawIterator & operator++()
TriaActiveIterator< Accessor > & operator=(const TriaActiveIterator< Accessor > &)
IteratorState::IteratorStates state() const
TriaRawIterator & operator--()
TriaIterator< Accessor > & operator=(const TriaIterator< Accessor > &)
DeclException0(ExcAdvanceInvalidObject)
OS & operator<<(OS &o, const Event &e)
Definition: event.h:304
TriaIterator< Accessor > & operator--()
TriaRawIterator & operator=(const TriaRawIterator &)
bool operator!=(const TriaRawIterator &) const
bool operator==(const TriaRawIterator &) const
const Accessor & access_any() const
DeclException1(ExcDereferenceInvalidCell, Accessor,<< "You tried to dereference a cell iterator for which this "<< "is not possible. More information on this iterator: "<< "level="<< arg1.level()<< ", index="<< arg1.index()<< ", state="<< (arg1.state()==IteratorState::valid?"valid":(arg1.state()==IteratorState::past_the_end?"past_the_end":"invalid")))
bool operator<(const TriaRawIterator &) const