FilteredIterator< BaseIterator > Class Template Reference
[Grid classesIterators on mesh-like containers]

Inheritance diagram for FilteredIterator< BaseIterator >:

Inheritance graph
[legend]

List of all members.

Classes

class  ExcInvalidElement
class  PredicateBase
class  PredicateTemplate

Public Types

typedef BaseIterator::AccessorType AccessorType

Public Member Functions

template<typename Predicate >
 FilteredIterator (Predicate p)
template<typename Predicate >
 FilteredIterator (Predicate p, const BaseIterator &bi)
 FilteredIterator (const FilteredIterator &fi)
 ~FilteredIterator ()
FilteredIteratoroperator= (const FilteredIterator &fi)
FilteredIteratoroperator= (const BaseIterator &fi)
FilteredIteratorset_to_next_positive (const BaseIterator &bi)
FilteredIteratorset_to_previous_positive (const BaseIterator &bi)
bool operator== (const FilteredIterator &fi) const
bool operator== (const BaseIterator &fi) const
bool operator!= (const FilteredIterator &fi) const
bool operator!= (const BaseIterator &fi) const
bool operator< (const FilteredIterator &fi) const
bool operator< (const BaseIterator &fi) const
FilteredIteratoroperator++ ()
FilteredIterator operator++ (int)
FilteredIteratoroperator-- ()
FilteredIterator operator-- (int)

Private Attributes

const PredicateBasepredicate


Detailed Description

template<typename BaseIterator>
class FilteredIterator< BaseIterator >

This class provides a certain view on a range of triangulation or DoFHandler iterators by only iterating over elements that satisfy a given filter (called a predicate, following the notation of the C++ standard library). Once initialized with a predicate and a value for the iterator, a filtered iterator hops to the next or previous element that satisfies the predicate if operators ++ or -- are invoked. Intermediate iterator values that lie in between but do not satisfy the predicate are skipped. It is thus very simple to write loops over a certain class of objects without the need to explicitely write down the condition they have to satisfy in each loop iteration. This in particular is helpful if functions are called with a pair of iterators denoting a range on which they shall act, by choosing a filtered iterator instead of usual ones.

Predicates

The object that represent the condition an iterator has to satisfy only have to provide an interface that allows to call the evaluation operator, i.e. bool operator() (const BaseIterator&). This includes function pointers as well as classes that implement an bool operator ()(const BaseIterator&). Then, the FilteredIterator will skip all objects where the return value of this function is false.

An example of a simple valid predicate is the following: given the function

   template <typename BIterator>
   bool level_equal_to_3 (const BIterator& c)
   {
     return (static_cast<unsigned int>(c->level()) == 3);
   };
then
   &level_equal_to_3<typename Triangulation<dim>::active_cell_iterator>
is a valid predicate.

Likewise, given the following binary function

   template <typename BIterator>
   bool level_equal_to (const BIterator&     c,
                        const unsigned int level)
   {
     return (static_cast<unsigned int>(c->level()) == level);
   };
then
   std::bind2nd (std::ptr_fun(&level_equal_to<active_cell_iterator>), 3)
is another valid predicate (here: a function that returns true if either the iterator is past the end or the level is equal to the second argument; this second argument is bound to a fixed value using the std::bind2nd function).

Finally, classes can be predicates. The following class is one:

   class Active 
   {
     public:
       template <class Iterator>
       bool operator () (const Iterator &i) const {
         return (i->active());
       }
   };
and objects of this type can be used as predicates. Likewise, this more complicated one can also be used:
   class SubdomainEqualTo
   {
     public:
       SubdomainEqualTo (const unsigned int subdomain_id)
                   : subdomain_id (subdomain_id) {};

       template <class Iterator>
       bool operator () (const Iterator &i) const {
         return (i->subdomain_id() == subdomain_id);
       }

     private:
       const unsigned int subdomain_id;
   };
Objects like SubdomainEqualTo(3) can then be used as predicates.

Since whenever a predicate is evaluated it is checked that the iterator checked is actually valid (i.e. not past the end), no checks for this case have to be performed inside predicates.

A number of filter classes are already implemented in the IteratorFilters namespace, but writing different ones is simple following the examples above.

Initialization of filtered iterators

Filtered iterators are given a predicate at construction time which cannot be changed any more. This behaviour would be expected if the predicate would have been given as a template parameter to the class, but since that would make the declaration of filtered iterators a nightmare, we rather give the predicate as an unchangeable entity to the constructor. Note that one can assign a filtered iterator with one predicate to another filtered iterator with another type; yet, this does not change the predicate of the assigned-to iterator, only the pointer indicating the iterator is changed.

If a filtered iterator is not assigned a value of the underlying (unfiltered) iterator type, the default value is taken. If, however, a value is given to the constructor, that value has either to be past the end, or has to satisfy the predicate. For example, if the predicate only evaluates to true if the level of an object is equal to three, then tria.begin_active(3) would be a valid choice while tria.begin() would not since the latter also returns iterators to non-active cells which always start at level 0.

Since one often only has some iterator and wants to set a filtered iterator to the first one that satisfies a predicate (for example, the first one for which the user flag is set, or the first one with a given subdomain id), there are assignement functions set_to_next_positive and set_to_previous_positive that assign the next or last previous iterator that satisfies the predicate, i.e. they follow the list of iterators in either direction until they find a matching one (or the past-the-end iterator). Like the operator= they return the resulting value of the filtered iterator.

Examples

The following call counts the number of active cells that have a set user flag:

   FilteredIterator<typename Triangulation<dim>::active_cell_iterator>
      begin (IteratorFilters::UserFlagSet()),
      end (IteratorFilters::UserFlagSet());
   begin.set_to_next_positive(tria.begin_active());
   end = tria.end();
   n_flagged_cells = std::distance (begin, end);
Note that by the set_to_next_positive call the first cell with a set user flag was assigned to the begin iterator. For the end} iterator, no such call was necessary, since the past-the-end iterator always satisfies all predicates.

The same can be achieved by the following snippet, though harder to read:

   typedef FilteredIterator<typename Triangulation<dim>::active_cell_iterator> FI;
   n_flagged_cells =
      std::distance (FI(IteratorFilters::UserFlagSet())
                            .set_to_next_positive(tria.begin_active()),
                     FI(IteratorFilters::UserFlagSet(), tria.end()));
It relies on the fact that if we create an unnamed filtered iterator with a given predicate but no iterator value and assign it the next positive value with respect to this predicate, it returns itself which is then used as the first parameter to the std::distance function. This procedure is not necessary for the end element to this function here, since the past-the-end iterator always satisfies the predicate so that we can assign this value to the filtered iterator directly in the constructor.

Finally, the following loop only assembles the matrix on cells with subdomain id equal to three:

 FilteredIterator<typename Triangulation<dim>::active_cell_iterator>
   cell (IteratorFilters::SubdomainEqualTo(3)),
   endc (IteratorFilters::SubdomainEqualTo(3), tria.end());
 cell.set_to_next_positive (tria.begin_active());
 for (; cell!=endc; ++cell)
   assemble_local_matrix (cell);

Since comparison between filtered and unfiltered iterators is defined, we could as well have let the endc variable in the last example be of type Triangulation<dim>::active_cell_iterator since it is unchanged and its value does not depend on the filter.

Author:
Wolfgang Bangerth, 2002

Member Typedef Documentation

template<typename BaseIterator>
typedef BaseIterator::AccessorType FilteredIterator< BaseIterator >::AccessorType

Typedef to the accessor type of the underlying iterator.


Constructor & Destructor Documentation

template<typename BaseIterator >
template<typename Predicate >
FilteredIterator< BaseIterator >::FilteredIterator ( Predicate  p  )  [inline]

Constructor. Set the iterator to the default state and use the given predicate for filtering subsequent assignement and iteration.

template<typename BaseIterator >
template<typename Predicate >
FilteredIterator< BaseIterator >::FilteredIterator ( Predicate  p,
const BaseIterator bi 
) [inline]

Constructor. Use the given predicate for filtering and initialize the iterator with the given value. This initial value has to satisfy the predicate.

References Assert, FilteredIterator< BaseIterator >::predicate, and IteratorState::valid.

template<typename BaseIterator >
FilteredIterator< BaseIterator >::FilteredIterator ( const FilteredIterator< BaseIterator > &  fi  )  [inline]

Copy constructor. Copy the predicate and iterator value of the given argument.

template<typename BaseIterator >
FilteredIterator< BaseIterator >::~FilteredIterator (  )  [inline]


Member Function Documentation

template<typename BaseIterator >
FilteredIterator< BaseIterator > & FilteredIterator< BaseIterator >::operator= ( const FilteredIterator< BaseIterator > &  fi  )  [inline]

Assignment operator. Copy the iterator value of the argument, but as discussed in the class documentation, the predicate of the argument is not copied. The iterator value underlying the argument has to satisfy the predicate of the object assigned to, as given at its construction time.

References Assert, FilteredIterator< BaseIterator >::predicate, and IteratorState::valid.

Referenced by FilteredIterator< BaseIterator >::operator=(), FilteredIterator< BaseIterator >::set_to_next_positive(), and FilteredIterator< BaseIterator >::set_to_previous_positive().

template<typename BaseIterator >
FilteredIterator< BaseIterator > & FilteredIterator< BaseIterator >::operator= ( const BaseIterator fi  )  [inline]

Assignment operator. Copy the iterator value of the argument, and keep the predicate of this object. The given iterator value has to satisfy the predicate of the object assigned to, as given at its construction time.

References Assert, FilteredIterator< BaseIterator >::operator=(), FilteredIterator< BaseIterator >::predicate, and IteratorState::valid.

template<typename BaseIterator >
FilteredIterator< BaseIterator > & FilteredIterator< BaseIterator >::set_to_next_positive ( const BaseIterator bi  )  [inline]

Search for the next iterator from bi onwards that satisfies the predicate of this object and assign it to this object.

Since filtered iterators are automatically converted to the underlying base iterator type, you can also give a filtered iterator as argument to this function.

References FilteredIterator< BaseIterator >::operator++(), FilteredIterator< BaseIterator >::operator=(), FilteredIterator< BaseIterator >::predicate, and IteratorState::valid.

template<typename BaseIterator >
FilteredIterator< BaseIterator > & FilteredIterator< BaseIterator >::set_to_previous_positive ( const BaseIterator bi  )  [inline]

As above, but search for the previous iterator from bi backwards that satisfies the predicate of this object and assign it to this object.

Since filtered iterators are automatically converted to the underlying base iterator type, you can also give a filtered iterator as argument to this function.

References FilteredIterator< BaseIterator >::operator--(), FilteredIterator< BaseIterator >::operator=(), FilteredIterator< BaseIterator >::predicate, and IteratorState::valid.

template<typename BaseIterator >
bool FilteredIterator< BaseIterator >::operator== ( const FilteredIterator< BaseIterator > &  fi  )  const [inline]

Compare for equality of the underlying iterator values of this and the given object.

We do not compare for equality of the predicates.

template<typename BaseIterator >
bool FilteredIterator< BaseIterator >::operator== ( const BaseIterator fi  )  const [inline]

Compare for equality of the underlying iterator value of this object with the given object.

The predicate of this object is irrelevant for this operation.

template<typename BaseIterator >
bool FilteredIterator< BaseIterator >::operator!= ( const FilteredIterator< BaseIterator > &  fi  )  const [inline]

Compare for inequality of the underlying iterator values of this and the given object.

We do not compare for equality of the predicates.

template<typename BaseIterator >
bool FilteredIterator< BaseIterator >::operator!= ( const BaseIterator fi  )  const [inline]

Compare for inequality of the underlying iterator value of this object with the given object.

The predicate of this object is irrelevant for this operation.

template<typename BaseIterator >
bool FilteredIterator< BaseIterator >::operator< ( const FilteredIterator< BaseIterator > &  fi  )  const [inline]

Compare for ordering of the underlying iterator values of this and the given object.

We do not compare the predicates.

template<typename BaseIterator >
bool FilteredIterator< BaseIterator >::operator< ( const BaseIterator fi  )  const [inline]

Compare for ordering of the underlying iterator value of this object with the given object.

The predicate of this object is irrelevant for this operation.

template<typename BaseIterator >
FilteredIterator< BaseIterator > & FilteredIterator< BaseIterator >::operator++ (  )  [inline]

Prefix advancement operator: move to the next iterator value satisfying the predicate and return the new iterator value.

References FilteredIterator< BaseIterator >::predicate, and IteratorState::valid.

Referenced by FilteredIterator< BaseIterator >::operator++(), and FilteredIterator< BaseIterator >::set_to_next_positive().

template<typename BaseIterator >
FilteredIterator< BaseIterator > FilteredIterator< BaseIterator >::operator++ ( int   )  [inline]

Postfix advancement operator: move to the next iterator value satisfying the predicate and return the old iterator value.

References FilteredIterator< BaseIterator >::operator++(), FilteredIterator< BaseIterator >::predicate, and IteratorState::valid.

template<typename BaseIterator >
FilteredIterator< BaseIterator > & FilteredIterator< BaseIterator >::operator-- (  )  [inline]

Prefix decrement operator: move to the previous iterator value satisfying the predicate and return the new iterator value.

References FilteredIterator< BaseIterator >::predicate, and IteratorState::valid.

Referenced by FilteredIterator< BaseIterator >::operator--(), and FilteredIterator< BaseIterator >::set_to_previous_positive().

template<typename BaseIterator >
FilteredIterator< BaseIterator > FilteredIterator< BaseIterator >::operator-- ( int   )  [inline]

Postfix advancement operator: move to the previous iterator value satisfying the predicate and return the old iterator value.

References FilteredIterator< BaseIterator >::operator--(), FilteredIterator< BaseIterator >::predicate, and IteratorState::valid.


Member Data Documentation

template<typename BaseIterator>
const PredicateBase* FilteredIterator< BaseIterator >::predicate [private]


The documentation for this class was generated from the following file:

deal.II documentation generated on Sat Aug 15 16:51:57 2009 by doxygen 1.5.9