![]() |
Reference documentation for deal.II version 9.6.0
|
#include <deal.II/grid/filtered_iterator.h>
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 Symbols | |
(Note that these are not member symbols.) | |
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) |
template<typename BaseIterator , typename Predicate > | |
IteratorRange< FilteredIterator< BaseIterator > > | operator| (IteratorRange< BaseIterator > i, const Predicate &p) |
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 advances 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. The use of this class is particularly useful when writing "ranged-based" for
loops of the form
An example is to write
where the resulting loop iterates over all active cells that are also locally owned and that point to cells that are at the boundary of the domain.
This class implements functionality comparable to what was added to C++20 in the form of range adaptors and the filters and filter views that represent them.
This class is used in step-32.
The object that represent the condition an iterator has to satisfy only has 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
then
is a valid predicate.
Likewise, given the following binary function
then the lambda function
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:
and objects of this type can be used as predicates. Likewise, this more complicated one can also be used:
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.
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.
The following call counts the number of active cells that have a set user flag:
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:
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:
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 632 of file filtered_iterator.h.
using FilteredIterator< BaseIterator >::AccessorType = typename BaseIterator::AccessorType |
Typedef to the accessor type of the underlying iterator.
Definition at line 638 of file filtered_iterator.h.
|
inline |
Constructor. Set the iterator to the default state and use the given predicate for filtering subsequent assignment and iteration.
Definition at line 1158 of file filtered_iterator.h.
|
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
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 1167 of file filtered_iterator.h.
|
inline |
Copy constructor. Copy the predicate and iterator value of the given argument.
Definition at line 1179 of file filtered_iterator.h.
|
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 1193 of file filtered_iterator.h.
|
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 1208 of file filtered_iterator.h.
|
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 1220 of file filtered_iterator.h.
|
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 1233 of file filtered_iterator.h.
|
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 1246 of file filtered_iterator.h.
|
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 1276 of file filtered_iterator.h.
|
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 1256 of file filtered_iterator.h.
|
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 1285 of file filtered_iterator.h.
|
inline |
Compare for ordering of the underlying iterator values of this and the given object.
We do not compare the predicates.
Definition at line 1265 of file filtered_iterator.h.
|
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 1293 of file filtered_iterator.h.
|
inline |
Prefix advancement operator: move to the next iterator value satisfying the predicate and return the new iterator value.
Definition at line 1302 of file filtered_iterator.h.
|
inline |
Postfix advancement operator: move to the next iterator value satisfying the predicate and return the old iterator value.
Definition at line 1315 of file filtered_iterator.h.
|
inline |
Prefix decrement operator: move to the previous iterator value satisfying the predicate and return the new iterator value.
Definition at line 1330 of file filtered_iterator.h.
|
inline |
Postfix advancement operator: move to the previous iterator value satisfying the predicate and return the old iterator value.
Definition at line 1343 of file filtered_iterator.h.
|
related |
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 904 of file filtered_iterator.h.
|
private |
Pointer to an object that encapsulated the actual data type of the predicate given to the constructor.
Definition at line 886 of file filtered_iterator.h.