From: guido Date: Tue, 12 Jul 2005 20:57:02 +0000 (+0000) Subject: Essay on iterators X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=5f08051d4927d4a0e9bd2db533688d028848f858;p=dealii-svn.git Essay on iterators git-svn-id: https://svn.dealii.org/trunk@11126 0785d39b-7218-0410-832d-ea1e28bc413d --- diff --git a/deal.II/doc/doxygen/headers/deal.II/iterators.h b/deal.II/doc/doxygen/headers/deal.II/iterators.h new file mode 100644 index 0000000000..6d6e387f68 --- /dev/null +++ b/deal.II/doc/doxygen/headers/deal.II/iterators.h @@ -0,0 +1,85 @@ +/** +@page Iterators Iterators on mesh like containers + +deal.II has several classes which are understood conceptionally as +meshes. Apart from the obvious Triangulation, these are DoFHandler and +MGDoFHandler. All of those define a set of iterators, allowing the +user to traverse the whole mesh or portions of it. Therefore, they +have somethings in common. In fact, these iterators are instantiations +or subclasses of the same class TriaIterator (we do not include +TriaRawIterator here, since it is only for internal use), + +The template signature of TriaIterator is +@code + TriaIterator +@endcode + +Usually, you will not use this definition directly, but employ one of +the typedefs below. + +@section IteratorsDifferences Distinguishing between iterators + +The iterators discussed are all of the form +@code + LoopIterator +@endcode + +Here, Loop determines, which cells are reached (or omitted, +for that matter). This means, independent of the accessor type, this +part of the definition of the iterator determines the meaning of the +increment operator. + +@subsection IteratorsLoops The action of the iterator itself + +All iterators with the same Loop and iterating over the +same kind of geometrical objects traverse the mesh in the same +order. Take this code example: +@code + Triangulation tria; + DoFHandler dof1(tria); + DoFHandler dof2(tria); + ... + Trianguation::active_cell_iterator ti = tria.begin_active(); + DoFHandler::active_cell_iterator di1 = dof1.begin_active(); + DoFHandler::active_cell_iterator di2 = dof2.begin_active(); + ... + while (ti != tria.end()) + { + do_something_with_iterators(ti, di1, di2); + ++ti; + ++di1; + ++di2; + } +@endcode + +Here, all iterators will always point to the same mesh cell, even if +the DoFHandlers are handling different finite elements. This +distinction is only in the Accessor. + +The standard loops are +
+
TriaIterator +
Traverse all cells on all levels
+ +
TriaActiveIterator +
Loop over @ref GlossActive "active cells" only
+
+ +@subsection IteratorsAccessors Accessors + +We just saw that iterators are not very clever and just know how to +march through a mesh. Whatever you actually can do with this iterator +is determined by the Accessor. The magic is, that for any iterator +i, the term i-> grants access to all +attributes of this Accessor. + + +@section IteratorsTypedefs Iterators defined in the containers + +The standard iterators are typedefed inside the classes. These are + + + + + +
cell_iteratorface_iterator