#include <deal.II/grid/filtered_iterator.h>

Inheritance diagram for FilteredIterator< BaseIterator >:

Classes
class	PredicateBase

class	PredicateTemplate

Public Types
using	AccessorType = typename BaseIterator::AccessorType

Public Member Functions
template<typename Predicate >
	FilteredIterator (Predicate p)

template<typename Predicate >
	FilteredIterator (Predicate p, const BaseIterator &bi)

	FilteredIterator (const FilteredIterator &fi)

FilteredIterator &	operator= (const FilteredIterator &fi)

FilteredIterator &	operator= (const BaseIterator &fi)

FilteredIterator &	set_to_next_positive (const BaseIterator &bi)

FilteredIterator &	set_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

FilteredIterator &	operator++ ()

FilteredIterator	operator++ (int)

FilteredIterator &	operator-- ()

FilteredIterator	operator-- (int)

Static Public Member Functions
static ::ExceptionBase &	ExcInvalidElement (BaseIterator arg1)

Private Attributes
std::unique_ptr< const PredicateBase >	predicate

Related Functions
(Note that these are not member functions.)
template<typename BaseIterator , typename Predicate >
FilteredIterator< BaseIterator >	make_filtered_iterator (const BaseIterator &i, const Predicate &p)

template<typename BaseIterator , typename Predicate >
IteratorRange< FilteredIterator< BaseIterator > >	filter_iterators (IteratorRange< BaseIterator > i, const Predicate &p)

template<typename BaseIterator , typename Predicate , typename... Targs>
IteratorRange< typename internal::FilteredIteratorImplementation::NestFilteredIterators< BaseIterator, std::tuple< Predicate, Targs... > >::type >	filter_iterators (IteratorRange< BaseIterator > i, const Predicate &p, const Targs... args)

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 explicitly 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.

This class is used in step-32.

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

[](const BIterator& c){ return level_equal_to<active_cell_iterator>(c, 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 taken considered fixed when creating the lambda 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->is_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 types::subdomain_id subdomain_id)
    : subdomain_id (subdomain_id)
  {};
 
  template <class Iterator>
  bool operator () (const Iterator &i) const
  {
    return (i->subdomain_id() == subdomain_id);
  }
 
private:
  const types::subdomain_id 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 behavior 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 assignment 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:

using FI =
  FilteredIterator<typename Triangulation<dim>::active_cell_iterator>;
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::active_cell_iterator since it is unchanged and its value does not depend on the filter.

Definition at line 524 of file filtered_iterator.h.

Member Typedef Documentation

◆ AccessorType

template<typename BaseIterator >

using FilteredIterator< BaseIterator >::AccessorType = typename BaseIterator::AccessorType

Typedef to the accessor type of the underlying iterator.

Definition at line 530 of file filtered_iterator.h.

Constructor & Destructor Documentation

◆ FilteredIterator() [1/3]

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 assignment and iteration.

Definition at line 925 of file filtered_iterator.h.

◆ FilteredIterator() [2/3]

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.

If the initial value bi does not satisfy the predicate p then it is advanced until we either hit the past-the-end iterator, or the predicate is satisfied. This allows, for example, to write code like

FilteredIterator<typename Triangulation<dim>::active_cell_iterator>
  cell (IteratorFilters::SubdomainEqualTo(13),
        triangulation.begin_active());

If the cell triangulation.begin_active() does not have a subdomain_id equal to 13, then the iterator will automatically be advanced to the first cell that has.

Definition at line 933 of file filtered_iterator.h.

◆ FilteredIterator() [3/3]

template<typename BaseIterator >

FilteredIterator< BaseIterator >::FilteredIterator ( const FilteredIterator< BaseIterator > & fi )

inline

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

Definition at line 945 of file filtered_iterator.h.

Member Function Documentation

◆ operator=() [1/2]

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.

Definition at line 959 of file filtered_iterator.h.

◆ operator=() [2/2]

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.

Definition at line 974 of file filtered_iterator.h.

◆ set_to_next_positive()

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.

Definition at line 986 of file filtered_iterator.h.

◆ set_to_previous_positive()

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.

Definition at line 999 of file filtered_iterator.h.

◆ operator==() [1/2]

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.

Definition at line 1012 of file filtered_iterator.h.

◆ operator==() [2/2]

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.

Definition at line 1042 of file filtered_iterator.h.

◆ operator!=() [1/2]

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.

Definition at line 1022 of file filtered_iterator.h.

◆ operator!=() [2/2]

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.

Definition at line 1051 of file filtered_iterator.h.

◆ operator<() [1/2]

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.

Definition at line 1031 of file filtered_iterator.h.

◆ operator<() [2/2]

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.

Definition at line 1059 of file filtered_iterator.h.

◆ operator++() [1/2]

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.

Definition at line 1068 of file filtered_iterator.h.

◆ operator++() [2/2]

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.

Definition at line 1081 of file filtered_iterator.h.

◆ operator--() [1/2]

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.

Definition at line 1096 of file filtered_iterator.h.

◆ operator--() [2/2]

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.

Definition at line 1109 of file filtered_iterator.h.

Friends And Related Function Documentation

◆ make_filtered_iterator()

template<typename BaseIterator , typename Predicate >

FilteredIterator< BaseIterator > make_filtered_iterator	(	const BaseIterator &	i,
		const Predicate &	p
	)

Create an object of type FilteredIterator given the base iterator and predicate. This function makes the creation of temporary objects (for example as function arguments) a lot simpler because one does not have to explicitly specify the type of the base iterator by hand – it is deduced automatically here.

Definition at line 788 of file filtered_iterator.h.

Member Data Documentation

◆ predicate

template<typename BaseIterator >

std::unique_ptr<const PredicateBase> FilteredIterator< BaseIterator >::predicate

private

Pointer to an object that encapsulated the actual data type of the predicate given to the constructor.

Definition at line 772 of file filtered_iterator.h.

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

include/deal.II/grid/filtered_iterator.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Private Attributes

Related Functions

Detailed Description

Predicates

Initialization of filtered iterators

Examples

Member Typedef Documentation

◆ AccessorType

Constructor & Destructor Documentation

◆ FilteredIterator() [1/3]

◆ FilteredIterator() [2/3]

◆ FilteredIterator() [3/3]

Member Function Documentation

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ set_to_next_positive()

◆ set_to_previous_positive()

◆ operator==() [1/2]

◆ operator==() [2/2]

◆ operator!=() [1/2]

◆ operator!=() [2/2]

◆ operator<() [1/2]

◆ operator<() [2/2]

◆ operator++() [1/2]

◆ operator++() [2/2]

◆ operator--() [1/2]

◆ operator--() [2/2]

Friends And Related Function Documentation

◆ make_filtered_iterator()

Member Data Documentation

◆ predicate