filtered_iterator.h

Go to the documentation of this file.

// -----------------------------------------------------------------------------
//
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception OR LGPL-2.1-or-later
// Copyright (C) 2002 - 2025 by the deal.II authors
//
// This file is part of the deal.II library.
//
// Detailed license information governing the source code and contributions
// can be found in LICENSE.md and CONTRIBUTING.md at the top level directory.
//
// -----------------------------------------------------------------------------
 
#ifndef dealii_filtered_iterator_h
#define dealii_filtered_iterator_h
 
 
#include <deal.II/base/config.h>
 
#include <deal.II/base/exceptions.h>
#include <deal.II/base/iterator_range.h>
#include <deal.II/base/types.h>
 
#include <deal.II/grid/tria_iterator_base.h>
 
#include <memory>
#include <set>
#include <tuple>
 
#ifdef DEAL_II_HAVE_CXX20
#  include <concepts>
#endif
 
 
DEAL_II_NAMESPACE_OPEN
 

namespace IteratorFilters
{
  class Active
  {
  public:
    template <class Iterator>
    bool
    operator()(const Iterator &i) const;
  };

  class UserFlagSet
  {
  public:
    template <class Iterator>
    bool
    operator()(const Iterator &i) const;
  };
 

  class UserFlagNotSet
  {
  public:
    template <class Iterator>
    bool
    operator()(const Iterator &i) const;
  };
 

  class LevelEqualTo
  {
  public:
    LevelEqualTo(const unsigned int level);

    template <class Iterator>
    bool
    operator()(const Iterator &i) const;
 
  protected:
    const unsigned int level;
  };
 
 

  class SubdomainEqualTo
  {
  public:
    SubdomainEqualTo(const types::subdomain_id subdomain_id);

    template <class Iterator>
    bool
    operator()(const Iterator &i) const;
 
  protected:
    const types::subdomain_id subdomain_id;
  };
 
 

  class LocallyOwnedCell
  {
  public:
    template <class Iterator>
    bool
    operator()(const Iterator &i) const;
  };
 
 

  class LocallyOwnedLevelCell
  {
  public:
    template <class Iterator>
    bool
    operator()(const Iterator &i) const;
  };
 

  class MaterialIdEqualTo
  {
  public:
    MaterialIdEqualTo(const types::material_id material_id,
                      const bool               only_locally_owned = false);

    MaterialIdEqualTo(const std::set<types::material_id> &material_ids,
                      const bool only_locally_owned = false);

    template <class Iterator>
    bool
    operator()(const Iterator &i) const;
 
  protected:
    const std::set<types::material_id> material_ids;
    const bool only_locally_owned;
  };

  class ActiveFEIndexEqualTo
  {
  public:
    ActiveFEIndexEqualTo(const unsigned int active_fe_index,
                         const bool         only_locally_owned = false);

    ActiveFEIndexEqualTo(const std::set<unsigned int> &active_fe_indices,
                         const bool only_locally_owned = false);

    template <class Iterator>
    bool
    operator()(const Iterator &i) const;
 
  protected:
    const std::set<unsigned int> active_fe_indices;
    const bool only_locally_owned;
  };

  class AtBoundary
  {
  public:
    template <class Iterator>
    bool
    operator()(const Iterator &i) const;
  };
 

  class BoundaryIdEqualTo
  {
  public:
    BoundaryIdEqualTo(const types::boundary_id boundary_id);

    BoundaryIdEqualTo(const std::set<types::boundary_id> &boundary_ids);

    template <class Iterator>
    bool
    operator()(const Iterator &i) const;
 
  protected:
    const std::set<types::boundary_id> boundary_ids;
  };
 

  class ManifoldIdEqualTo
  {
  public:
    ManifoldIdEqualTo(const types::manifold_id manifold_id);

    ManifoldIdEqualTo(const std::set<types::manifold_id> &manifold_ids);

    template <class Iterator>
    bool
    operator()(const Iterator &i) const;
 
  protected:
    const std::set<types::manifold_id> manifold_ids;
  };
} // namespace IteratorFilters
 

template <typename BaseIterator>
class FilteredIterator : public BaseIterator
{
public:
  using AccessorType = typename BaseIterator::AccessorType;

  template <typename Predicate>
  DEAL_II_CXX20_REQUIRES((std::predicate<Predicate, BaseIterator>))
  FilteredIterator(Predicate p);

  template <typename Predicate>
  DEAL_II_CXX20_REQUIRES((std::predicate<Predicate, BaseIterator>))
  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);

  DeclException1(
    ExcInvalidElement,
    BaseIterator,
    << "The element " << arg1
    << " with which you want to compare or which you want to"
    << " assign from is invalid since it does not satisfy the predicate.");
 
private:
  class PredicateBase
  {
  public:
    virtual ~PredicateBase() = default;

    virtual bool
    operator()(const BaseIterator &bi) const = 0;
  };
 

  template <typename Predicate>
  class PredicateTemplate : public PredicateBase
  {
  public:
    PredicateTemplate(const Predicate &predicate);

    virtual bool
    operator()(const BaseIterator &bi) const override;
 
  private:
    const Predicate predicate;
  };

  std::shared_ptr<const PredicateBase> predicate;
};
 
 

template <typename BaseIterator, typename Predicate>
DEAL_II_CXX20_REQUIRES((std::predicate<Predicate, BaseIterator>))
FilteredIterator<BaseIterator> make_filtered_iterator(const BaseIterator &i,
                                                      const Predicate    &p)
{
  FilteredIterator<BaseIterator> fi(p);
  fi.set_to_next_positive(i);
  return fi;
}
 
 
 
namespace internal
{
  namespace FilteredIteratorImplementation
  {
    // The following classes create a nested sequence of
    // FilteredIterator<FilteredIterator<...<BaseIterator>...>> with as many
    // levels of FilteredIterator classes as there are elements in the TypeList
    // if the latter is given as a std::tuple<Args...>.
    template <typename BaseIterator, typename TypeList>
    struct NestFilteredIterators;
 
    template <typename BaseIterator, typename Predicate>
    struct NestFilteredIterators<BaseIterator, std::tuple<Predicate>>
    {
      using type = ::FilteredIterator<BaseIterator>;
    };
 
    template <typename BaseIterator, typename Predicate, typename... Targs>
    struct NestFilteredIterators<BaseIterator, std::tuple<Predicate, Targs...>>
    {
      using type = ::FilteredIterator<
        typename NestFilteredIterators<BaseIterator,
                                       std::tuple<Targs...>>::type>;
    };
  } // namespace FilteredIteratorImplementation
} // namespace internal
 
 

template <typename BaseIterator, typename Predicate>
DEAL_II_CXX20_REQUIRES((std::predicate<Predicate, BaseIterator>))
inline IteratorRange<FilteredIterator<BaseIterator>> filter_iterators(
  IteratorRange<BaseIterator> i,
  const Predicate            &p)
{
  FilteredIterator<BaseIterator> fi(p, *(i.begin()));
  FilteredIterator<BaseIterator> fi_end(p, *(i.end()));
 
  return IteratorRange<FilteredIterator<BaseIterator>>(fi, fi_end);
}
 
 

template <typename BaseIterator, typename Predicate, typename... Targs>
DEAL_II_CXX20_REQUIRES((std::predicate<Predicate, BaseIterator>))
IteratorRange<
  typename internal::FilteredIteratorImplementation::
    NestFilteredIterators<BaseIterator, std::tuple<Predicate, Targs...>>::
      type> filter_iterators(IteratorRange<BaseIterator> i,
                             const Predicate            &p,
                             const Targs... args)
{
  // Recursively create filtered iterators, one predicate at a time
  auto fi = filter_iterators(i, p);
  return filter_iterators(fi, args...);
}
 
 

template <typename BaseIterator, typename Predicate>
DEAL_II_CXX20_REQUIRES((std::predicate<Predicate, BaseIterator>))
inline IteratorRange<FilteredIterator<BaseIterator>>
operator|(IteratorRange<BaseIterator> i, const Predicate &p)
{
  return filter_iterators(i, p);
}
 
 
 
/* ------------------ Inline functions and templates ------------ */
 
 
template <typename BaseIterator>
template <typename Predicate>
DEAL_II_CXX20_REQUIRES((std::predicate<Predicate, BaseIterator>))
inline FilteredIterator<BaseIterator>::FilteredIterator(Predicate p)
  : predicate(std::make_shared<PredicateTemplate<Predicate>>(p))
{}
 
 
 
template <typename BaseIterator>
template <typename Predicate>
DEAL_II_CXX20_REQUIRES((std::predicate<Predicate, BaseIterator>))
inline FilteredIterator<BaseIterator>::FilteredIterator(Predicate           p,
                                                        const BaseIterator &bi)
  : BaseIterator(bi)
  , predicate(std::make_shared<PredicateTemplate<Predicate>>(p))
{
  if ((this->state() == IteratorState::valid) && !(*predicate)(*this))
    set_to_next_positive(bi);
}
 
 
 
template <typename BaseIterator>
inline FilteredIterator<BaseIterator>::FilteredIterator(
  const FilteredIterator &fi)
  : // this construction looks strange, but without going through the
    // address of fi, GCC would not cast fi to the base class of type
    // BaseIterator but tries to go through constructing a new
    // BaseIterator with an Accessor.
  BaseIterator(*static_cast<const BaseIterator *>(&fi))
  , predicate(fi.predicate)
{}
 
 
 
template <typename BaseIterator>
inline FilteredIterator<BaseIterator> &
FilteredIterator<BaseIterator>::operator=(const FilteredIterator &fi)
{
  // Using equivalent code to the one for 'operator=(const BaseIterator &bi)'
  // below, some compiler would not cast fi to the base class of type
  // BaseIterator but try to go through constructing a new Accessor from fi
  // which fails. Hence, we just use an explicit upcast and call the above-
  // mentioned method.
  const BaseIterator &bi = fi;
  return operator=(bi);
}
 
 
 
template <typename BaseIterator>
inline FilteredIterator<BaseIterator> &
FilteredIterator<BaseIterator>::operator=(const BaseIterator &bi)
{
  Assert((bi.state() != IteratorState::valid) || (*predicate)(bi),
         ExcInvalidElement(bi));
  BaseIterator::operator=(bi);
  return *this;
}
 
 
 
template <typename BaseIterator>
inline FilteredIterator<BaseIterator> &
FilteredIterator<BaseIterator>::set_to_next_positive(const BaseIterator &bi)
{
  BaseIterator::operator=(bi);
  while ((this->state() == IteratorState::valid) && (!(*predicate)(*this)))
    BaseIterator::operator++();
 
  return *this;
}
 
 
 
template <typename BaseIterator>
inline FilteredIterator<BaseIterator> &
FilteredIterator<BaseIterator>::set_to_previous_positive(const BaseIterator &bi)
{
  BaseIterator::operator=(bi);
  while ((this->state() == IteratorState::valid) && (!(*predicate)(*this)))
    BaseIterator::operator--();
 
  return *this;
}
 
 
 
template <typename BaseIterator>
inline bool
FilteredIterator<BaseIterator>::operator==(const FilteredIterator &fi) const
{
  return (static_cast<const BaseIterator &>(*this) ==
          static_cast<const BaseIterator &>(fi));
}
 
 
 
template <typename BaseIterator>
inline bool
FilteredIterator<BaseIterator>::operator!=(const FilteredIterator &fi) const
{
  return (static_cast<const BaseIterator &>(*this) !=
          static_cast<const BaseIterator &>(fi));
}
 
 
 
template <typename BaseIterator>
inline bool
FilteredIterator<BaseIterator>::operator<(const FilteredIterator &fi) const
{
  return (static_cast<const BaseIterator &>(*this) <
          static_cast<const BaseIterator &>(fi));
}
 
 
 
template <typename BaseIterator>
inline bool
FilteredIterator<BaseIterator>::operator==(const BaseIterator &bi) const
{
  return (static_cast<const BaseIterator &>(*this) == bi);
}
 
 
 
template <typename BaseIterator>
inline bool
FilteredIterator<BaseIterator>::operator!=(const BaseIterator &bi) const
{
  return (static_cast<const BaseIterator &>(*this) != bi);
}
 
 
 
template <typename BaseIterator>
inline bool
FilteredIterator<BaseIterator>::operator<(const BaseIterator &bi) const
{
  return (static_cast<const BaseIterator &>(*this) < bi);
}
 
 
template <typename BaseIterator>
inline FilteredIterator<BaseIterator> &
FilteredIterator<BaseIterator>::operator++()
{
  if (this->state() == IteratorState::valid)
    do
      BaseIterator::operator++();
    while ((this->state() == IteratorState::valid) && !(*predicate)(*this));
  return *this;
}
 
 
 
template <typename BaseIterator>
inline FilteredIterator<BaseIterator>
FilteredIterator<BaseIterator>::operator++(int)
{
  const FilteredIterator old_state = *this;
 
  if (this->state() == IteratorState::valid)
    do
      BaseIterator::operator++();
    while ((this->state() == IteratorState::valid) && !(*predicate)(*this));
  return old_state;
}
 
 
 
template <typename BaseIterator>
inline FilteredIterator<BaseIterator> &
FilteredIterator<BaseIterator>::operator--()
{
  if (this->state() == IteratorState::valid)
    do
      BaseIterator::operator--();
    while ((this->state() == IteratorState::valid) && !(*predicate)(*this));
  return *this;
}
 
 
 
template <typename BaseIterator>
inline FilteredIterator<BaseIterator>
FilteredIterator<BaseIterator>::operator--(int)
{
  const FilteredIterator old_state = *this;
 
  if (this->state() == IteratorState::valid)
    do
      BaseIterator::operator--();
    while ((this->state() == IteratorState::valid) && !(*predicate)(*this));
  return old_state;
}
 
 
 
template <typename BaseIterator>
template <typename Predicate>
inline FilteredIterator<BaseIterator>::PredicateTemplate<
  Predicate>::PredicateTemplate(const Predicate &predicate)
  : predicate(predicate)
{}
 
 
 
template <typename BaseIterator>
template <typename Predicate>
bool
FilteredIterator<BaseIterator>::PredicateTemplate<Predicate>::operator()(
  const BaseIterator &bi) const
{
  return predicate(bi);
}
 
 
 
namespace IteratorFilters
{
  // ---------------- IteratorFilters::Active ---------
 
  template <class Iterator>
  inline bool
  Active::operator()(const Iterator &i) const
  {
    return i->is_active();
  }
 
 
  // ---------------- IteratorFilters::UserFlagSet ---------
 
  template <class Iterator>
  inline bool
  UserFlagSet::operator()(const Iterator &i) const
  {
    return (i->user_flag_set());
  }
 
 
  // ---------------- IteratorFilters::UserFlagNotSet ---------
 
  template <class Iterator>
  inline bool
  UserFlagNotSet::operator()(const Iterator &i) const
  {
    return (!i->user_flag_set());
  }
 
 
  // ---------------- IteratorFilters::LevelEqualTo ---------
  inline LevelEqualTo::LevelEqualTo(const unsigned int level)
    : level(level)
  {}
 
 
 
  template <class Iterator>
  inline bool
  LevelEqualTo::operator()(const Iterator &i) const
  {
    return (static_cast<unsigned int>(i->level()) == level);
  }
 
 
 
  // ---------------- IteratorFilters::SubdomainEqualTo ---------
  inline SubdomainEqualTo::SubdomainEqualTo(
    const types::subdomain_id subdomain_id)
    : subdomain_id(subdomain_id)
  {}
 
 
 
  template <class Iterator>
  inline bool
  SubdomainEqualTo::operator()(const Iterator &i) const
  {
    return (i->subdomain_id() == subdomain_id);
  }
 
 
 
  // ---------------- IteratorFilters::LocallyOwnedCell ---------
 
  template <class Iterator>
  inline bool
  LocallyOwnedCell::operator()(const Iterator &i) const
  {
    return (i->is_locally_owned());
  }
 
 
  // ---------------- IteratorFilters::LocallyOwnedLevelCell ---------
 
  template <class Iterator>
  inline bool
  LocallyOwnedLevelCell::operator()(const Iterator &i) const
  {
    return (i->is_locally_owned_on_level());
  }
 
 
 
  // ---------------- IteratorFilters::MaterialIdEqualTo ---------
  inline MaterialIdEqualTo::MaterialIdEqualTo(
    const types::material_id material_id,
    const bool               only_locally_owned)
    : material_ids{material_id}
    , only_locally_owned(only_locally_owned)
  {}
 
 
 
  inline MaterialIdEqualTo::MaterialIdEqualTo(
    const std::set<types::material_id> &material_ids,
    const bool                          only_locally_owned)
    : material_ids(material_ids)
    , only_locally_owned(only_locally_owned)
  {}
 
 
 
  template <class Iterator>
  inline bool
  MaterialIdEqualTo::operator()(const Iterator &i) const
  {
    return only_locally_owned == true ?
             (material_ids.find(i->material_id()) != material_ids.end() &&
              i->is_locally_owned()) :
             material_ids.find(i->material_id()) != material_ids.end();
  }
 
 
 
  // ---------------- IteratorFilters::ActiveFEIndexEqualTo ---------
  inline ActiveFEIndexEqualTo::ActiveFEIndexEqualTo(
    const unsigned int active_fe_index,
    const bool         only_locally_owned)
    : active_fe_indices{active_fe_index}
    , only_locally_owned(only_locally_owned)
  {}
 
 
 
  inline ActiveFEIndexEqualTo::ActiveFEIndexEqualTo(
    const std::set<unsigned int> &active_fe_indices,
    const bool                    only_locally_owned)
    : active_fe_indices(active_fe_indices)
    , only_locally_owned(only_locally_owned)
  {}
 
 
 
  template <class Iterator>
  inline bool
  ActiveFEIndexEqualTo::operator()(const Iterator &i) const
  {
    return only_locally_owned == true ?
             (i->is_locally_owned() &&
              active_fe_indices.find(i->active_fe_index()) !=
                active_fe_indices.end()) :
             active_fe_indices.find(i->active_fe_index()) !=
               active_fe_indices.end();
  }
 
 
 
  // ---------------- IteratorFilters::AtBoundary ---------
 
  template <class Iterator>
  inline bool
  AtBoundary::operator()(const Iterator &i) const
  {
    return (i->at_boundary());
  }
 
 
 
  // ---------------- IteratorFilters::BoundaryIdEqualTo ---------
  inline BoundaryIdEqualTo::BoundaryIdEqualTo(
    const types::boundary_id boundary_id)
    : boundary_ids{boundary_id}
  {}
 
 
 
  inline BoundaryIdEqualTo::BoundaryIdEqualTo(
    const std::set<types::boundary_id> &boundary_ids)
    : boundary_ids(boundary_ids)
  {}
 
 
 
  template <class Iterator>
  inline bool
  BoundaryIdEqualTo::operator()(const Iterator &i) const
  {
    return boundary_ids.find(i->boundary_id()) != boundary_ids.end();
  }
 
 
 
  // ---------------- IteratorFilters::ManifoldIdEqualTo ---------
  inline ManifoldIdEqualTo::ManifoldIdEqualTo(
    const types::manifold_id manifold_id)
    : manifold_ids{manifold_id}
  {}
 
 
 
  inline ManifoldIdEqualTo::ManifoldIdEqualTo(
    const std::set<types::manifold_id> &manifold_ids)
    : manifold_ids(manifold_ids)
  {}
 
 
 
  template <class Iterator>
  inline bool
  ManifoldIdEqualTo::operator()(const Iterator &i) const
  {
    return manifold_ids.find(i->manifold_id()) != manifold_ids.end();
  }
} // namespace IteratorFilters
 
 
DEAL_II_NAMESPACE_CLOSE
 
#endif