]> https://gitweb.dealii.org/ - dealii-svn.git/commitdiff
Move some documentation. Document the new partial specialization of TriaAccessor.
authorbangerth <bangerth@0785d39b-7218-0410-832d-ea1e28bc413d>
Mon, 5 Mar 2007 23:09:54 +0000 (23:09 +0000)
committerbangerth <bangerth@0785d39b-7218-0410-832d-ea1e28bc413d>
Mon, 5 Mar 2007 23:09:54 +0000 (23:09 +0000)
git-svn-id: https://svn.dealii.org/trunk@14522 0785d39b-7218-0410-832d-ea1e28bc413d

deal.II/deal.II/include/grid/tria_accessor.h
deal.II/deal.II/include/grid/tria_accessor.templates.h
deal.II/doc/doxygen/headers/iterators.h

index b45d70fb7618bad51036d5fb784a1134cf7d856e..798cb2930198e1c1269152413accc33ae19d645a 100644 (file)
@@ -19,8 +19,6 @@
 #include <grid/tria_iterator_base.h>
 
 
-//TODO[WB]: since line and face iterators do not have levels, we can save a bit of memory by splitting TriaAccessor into a class for cells and one for everything else, and getting rid of the present_level field for the latter
-
 namespace std
 {
   template<class T1, class T2>
@@ -124,62 +122,23 @@ namespace TriaAccessorExceptions
 
 
 /**
- * Implements the accessor class used by TriaRawIterator and derived
- * classes.
+ * A base class for the accessor classes used by TriaRawIterator and
+ * derived classes.
  *
- * This class offers only the basic functionality erquired by the
+ * This class offers only the basic functionality required by the
  * iterators (stores the necessary data members, offers comparison
  * operators and the like), but has no functionality to actually
  * dereference data. This is done in the derived classes.
  *
- * <h3>Internals</h3>
- *   
- * There is a representation of past-the-end-pointers, denoted by
- * special values of the member variables #present_level and
- * #present_index: If #present_level>=0 and #present_index>=0, then
- * the object is valid (there is no check whether the triangulation
- * really has that many levels or that many cells on the present level
- * when we investigate the state of an iterator; however, in many
- * places where an iterator is dereferenced we make this check); if
- * #present_level==-1 and #present_index==-1, then the iterator points
- * past the end; in all other cases, the iterator is considered
- * invalid.  You can check this by calling the state() function.
- *
- * An iterator is also invalid, if the pointer pointing to the
- * Triangulation object is invalid or zero.
- *
- * Finally, an iterator is invalid, if the element pointed to by
- * #present_level and #present_index is not used, i.e. if the
- * <tt>used</tt> flag is set to false.
- *
- * The last two checks are not made in state() since both cases should
- * only occur upon unitialized construction through <tt>memcpy</tt>
- * and the like (the parent triangulation can only be set upon
- * construction). If an iterator is constructed empty through the
- * empty constructor, it sets #present_level==-2 and
- * #present_index==-2. Thus, the iterator is invalid anyway,
- * regardless of the state of the triangulation pointer and the state
- * of the element pointed to.
- *
- * Past-the-end iterators may also be used to compare an iterator with
- * the before-the-start value, when running backwards. There is no
- * distiction between the iterators pointing past the two ends of a
- * vector.
- *   
- * Defining only one value to be past-the-end and making all other
- * values invalid provides a second track of security: if we should
- * have forgotten a check in the library when an iterator is
- * incremented or decremented, we automatically convert the iterator
- * from the allowed state "past-the-end" to the disallowed state
- * "invalid" which increases the chance that somehwen earlier than for
- * past-the-end iterators an exception is raised.
+ * This template is used for faces and edges, which have no level in
+ * the triangulation hierarchy associated with them. There exists a
+ * partial specialization of the current class template where
+ * <tt>structdim</tt> (the dimensionality of the object represented,
+ * for example 1 for a line) equals <tt>dim</tt> (the dimensionality
+ * of the space the object lives in, for example 3 if we solve
+ * three-dimensional problems).
  *
- * Cells are stored based on a hierachical structure of levels, therefore
- * the above mentioned structure is useful. Faces however are not organized
- * in levels, therefore the #present_level variable is ignored in that
- * cases and is set to 0 for all faces. Several Accessor- and Iterator-
- * functions check for that value, if the object accessed is not a cell
- * but a face in the current triangulation.
+ * Some internals of this class are discussed in @ref IteratorAccessorInternals .
  *
  * @ingroup grid
  * @ingroup Accessors
@@ -335,6 +294,30 @@ class TriaAccessor
 
 
 
+/**
+ * A base class for the accessor classes used by TriaRawIterator and
+ * derived classes.
+ *
+ * This class offers only the basic functionality required by the
+ * iterators (stores the necessary data members, offers comparison
+ * operators and the like), but has no functionality to actually
+ * dereference data. This is done in the derived classes.
+ *
+ * This template is a partial specialization of the general template
+ * used for cells only, i.e. for the case where <tt>structdim</tt>
+ * (the dimensionality of the object represented, for example 1 for a
+ * line) equals <tt>dim</tt> (the dimensionality of the space the
+ * object lives in, for example 3 if we solve three-dimensional
+ * problems). The difference is that cells have a level in the
+ * triangulation hierarchy associated with them, whereas faces and
+ * edges do not.
+ *
+ * Some internals of this class are discussed in @ref IteratorAccessorInternals .
+ *
+ * @ingroup grid
+ * @ingroup Accessors
+ * @author Wolfgang Bangerth, 1998
+ */
 template <int dim>
 class TriaAccessor<dim,dim>
 {
index 2ce6b5f691681b9f03e895c4c25d01d790f0f94e..0e03942d1da0417f029b7c65d8837fcdab9444bb 100644 (file)
@@ -32,13 +32,22 @@ DEAL_II_NAMESPACE_OPEN
 template <int structdim, int dim>
 inline
 TriaAccessor<structdim,dim>::TriaAccessor (const Triangulation<dim> *parent,
-                                          const int                 /*level*/,
+                                          const int                 level,
                                           const int                 index,
                                           const AccessorData       *)
                 :
                 present_index (index),
                 tria (parent)
-{}
+{
+
+                                  // non-cells have no level, so a 0
+                                  // should have been passed, or a -1
+                                  // for an end-iterator, or -2 for
+                                  // an invalid (default constructed)
+                                  // iterator
+  Assert ((level == 0) || (level == -1) || (level == -2),
+         ExcInternalError());
+}
 
 
 
index 004392da32155a003858f6f67a80faa77c0663c7..0c0aba4a6d4ef2a888be08745920c692425c660c 100644 (file)
@@ -191,11 +191,18 @@ objects is the same for all iterators in the following snippet:
 
 Iterators are like pointers: they can be incremented and decremented, but they
 are really rather dumb. Their magic only lies in the fact that they point to
-some useful object, in this case the Accessor. Accessing data that
-characterizes a cell is always done through the Accessor, i.e. the expression
-<tt>i-&gt;</tt> grants access to <b>all</b> attributes of this Accessor.
-
-Examples of properties you can query from an iterator are
+some useful object, in this case the Accessor. For pointers, they point to an
+actual object that stores some data. On the other hand, the deal.II iterators,
+when dereferenced, do not return a reference to an actual object, but return
+an object that knows how to get at the data that represents cells. In general, this
+object doesn't store itself where the vertices of a cell are or what its neighbors
+are. However, it knows how to tease this sort of information from out of the
+arrays and tables and lists that the Triangulation class sets up to describe a
+mesh.
+
+Accessing data that characterizes a cell is always done through the Accessor,
+i.e. the expression <tt>i-&gt;</tt> grants access to <b>all</b> attributes of
+this Accessor. Examples of properties you can query from an iterator are
 @code
   cell->vertex(1);
   line->child(0);
@@ -355,6 +362,65 @@ a hexehedron in 3d), there are corresponding types and calls like
 dimension independent geometric objects line, quad, and hex. These calls,
 just as the ones above, exist in active and non-active forms.
 
+
+@section IteratorAccessorInternals Iterator and accessor internals
+
+Iterators, being like pointer, act as if they pointed to an actual
+object, but in reality all they do is to return an accessor when
+dereferenced. The accessor object contains the state, i.e. it knows
+which object it represents, by storing for example which Triangulation
+it belongs to, and the level and index within this level of a cell. It
+is therefore able to access the data that corresponds to the cell (or
+face, or edge) it represents
+
+There is a representation of past-the-end-pointers, denoted by special
+values of the member variables #present_level and #present_index in
+the TriaAccessor class: If #present_level>=0 and #present_index>=0,
+then the object is valid (there is no check whether the triangulation
+really has that many levels or that many cells on the present level
+when we investigate the state of an iterator; however, in many places
+where an iterator is dereferenced we make this check); if
+#present_level==-1 and #present_index==-1, then the iterator points
+past the end; in all other cases, the iterator is considered invalid.
+You can check this by calling the state() function.
+
+An iterator is also invalid, if the pointer pointing to the
+Triangulation object is invalid or zero.
+
+Finally, an iterator is invalid, if the element pointed to by
+#present_level and #present_index is not used, i.e. if the
+<tt>used</tt> flag is set to false.
+
+The last two checks are not made in state() since both cases should
+only occur upon unitialized construction through <tt>memcpy</tt>
+and the like (the parent triangulation can only be set upon
+construction). If an iterator is constructed empty through the
+empty constructor, it sets #present_level==-2 and
+#present_index==-2. Thus, the iterator is invalid anyway,
+regardless of the state of the triangulation pointer and the state
+of the element pointed to.
+
+Past-the-end iterators may also be used to compare an iterator with
+the before-the-start value, when running backwards. There is no
+distiction between the iterators pointing past the two ends of a
+vector.
+
+Defining only one value to be past-the-end and making all other
+values invalid provides a second track of security: if we should
+have forgotten a check in the library when an iterator is
+incremented or decremented, we automatically convert the iterator
+from the allowed state "past-the-end" to the disallowed state
+"invalid" which increases the chance that somehwen earlier than for
+past-the-end iterators an exception is raised.
+
+Cells are stored based on a hierachical structure of levels, therefore
+the above mentioned structure is useful. Faces however are not organized
+in levels, therefore the #present_level variable is ignored in that
+cases and is set to 0 for all faces. Several Accessor- and Iterator-
+functions check for that value, if the object accessed is not a cell
+but a face in the current triangulation.
+
+
 @ingroup grid
 */
 

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.