tria_iterator.h

Go to the documentation of this file.

// ---------------------------------------------------------------------
//
// Copyright (C) 1998 - 2023 by the deal.II authors
//
// This file is part of the deal.II library.
//
// The deal.II library is free software; you can use it, redistribute
// it, and/or modify it under the terms of the GNU Lesser General
// Public License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
// The full text of the license can be found in the file LICENSE.md at
// the top level directory of deal.II.
//
// ---------------------------------------------------------------------
 
#ifndef dealii_tria_iterator_h
#define dealii_tria_iterator_h
 
 
#include <deal.II/base/config.h>
 
#include <deal.II/base/exceptions.h>
#include <deal.II/base/point.h>
 
#include <deal.II/grid/tria_iterator_base.h>
 
#include <iterator>
#include <ostream>
 
DEAL_II_NAMESPACE_OPEN
 
// Forward declarations
#ifndef DOXYGEN
template <int dim, int spacedim>
DEAL_II_CXX20_REQUIRES((concepts::is_valid_dim_spacedim<dim, spacedim>))
class Triangulation;
template <int, int, int>
class TriaAccessorBase;
 
template <typename>
class TriaIterator;
template <typename>
class TriaActiveIterator;
#endif
 
 
 
// note: in non-debug mode, i.e. with optimizations, the file
// tria_iterator.templates.h is included at the end of this file.
// this includes a lot of templates and thus makes compilation
// slower, but at the same time allows for more aggressive
// inlining and thus faster code.
 
 
template <typename Accessor>
class TriaRawIterator
{
public:
  using AccessorType = Accessor;
 
  TriaRawIterator();
 
  TriaRawIterator(const TriaRawIterator &);
 
  explicit TriaRawIterator(const Accessor &a);
 
  template <typename OtherAccessor>
  explicit TriaRawIterator(const OtherAccessor &a);
 
  TriaRawIterator(
    const Triangulation<Accessor::dimension, Accessor::space_dimension> *parent,
    const int                                                            level,
    const int                                                            index,
    const typename AccessorType::AccessorData *local_data = nullptr);
 
  template <typename OtherAccessor>
  TriaRawIterator(const TriaRawIterator<OtherAccessor> &i);
 
  TriaRawIterator(
    const TriaAccessorBase<Accessor::structure_dimension,
                           Accessor::dimension,
                           Accessor::space_dimension> &tria_accessor,
    const typename Accessor::AccessorData *            local_data);
 
  template <typename OtherAccessor>
  TriaRawIterator(const TriaIterator<OtherAccessor> &i);
 
  template <typename OtherAccessor>
  TriaRawIterator(const TriaActiveIterator<OtherAccessor> &i);
 
  const Accessor &
  operator*() const;
 
  Accessor &
  operator*();
 
  const Accessor *
  operator->() const;
 
  Accessor *
  operator->();
 
 
  const Accessor &
  access_any() const;
 
  TriaRawIterator &
  operator=(const TriaRawIterator &);
 
  template <typename OtherAccessor = Accessor>
  std::enable_if_t<std::is_convertible<OtherAccessor, Accessor>::value, bool>
  operator==(const TriaRawIterator<OtherAccessor> &) const;
 
  bool
  operator!=(const TriaRawIterator &) const;
 
  bool
  operator<(const TriaRawIterator &) const;
 
  bool
  operator>(const TriaRawIterator &) const;
 
  TriaRawIterator &
  operator++();
 
  TriaRawIterator
  operator++(int);
 
  TriaRawIterator &
  operator--();
 
  TriaRawIterator
  operator--(int);
  IteratorState::IteratorStates
  state() const;
 
  template <class StreamType>
  void
  print(StreamType &out) const;
 
 
  std::size_t
  memory_consumption() const;
 
  using iterator_category = std::bidirectional_iterator_tag;
  using value_type        = Accessor;
  using difference_type   = int;
  using pointer           = Accessor *;
  using reference         = Accessor &;
 
  DeclException1(ExcDereferenceInvalidCell,
                 Accessor,
                 << "You tried to dereference a cell iterator for which this "
                 << "is not possible. More information on this iterator: "
                 << "level=" << arg1.level() << ", index=" << arg1.index()
                 << ", state="
                 << (arg1.state() == IteratorState::valid ?
                       "valid" :
                       (arg1.state() == IteratorState::past_the_end ?
                          "past_the_end" :
                          "invalid")));
 
  DeclException1(ExcDereferenceInvalidObject,
                 Accessor,
                 << "You tried to dereference an iterator for which this "
                 << "is not possible. More information on this iterator: "
                 << "index=" << arg1.index() << ", state="
                 << (arg1.state() == IteratorState::valid ?
                       "valid" :
                       (arg1.state() == IteratorState::past_the_end ?
                          "past_the_end" :
                          "invalid")));
 
  DeclException0(ExcAdvanceInvalidObject);
  DeclException0(ExcInvalidComparison);
 
protected:
  Accessor accessor;
 
 
  // Make all other iterator class templates friends of this class. This is
  // necessary for the implementation of conversion constructors.
  //
  // In fact, we would not need them to be friends if they were for different
  // dimensions, but the compiler dislikes giving a fixed dimension and
  // variable accessor since then it says that would be a partial
  // specialization.
  template <typename SomeAccessor>
  friend class TriaRawIterator;
  template <typename SomeAccessor>
  friend class TriaIterator;
  template <typename SomeAccessor>
  friend class TriaActiveIterator;
};
 
 
template <typename Accessor>
class TriaIterator : public TriaRawIterator<Accessor>
{
public:
  TriaIterator();
 
  TriaIterator(const TriaIterator<Accessor> &);
 
  TriaIterator(const TriaRawIterator<Accessor> &);
 
  TriaIterator(
    const Triangulation<Accessor::dimension, Accessor::space_dimension> *parent,
    const int                                                            level,
    const int                                                            index,
    const typename Accessor::AccessorData *local_data = nullptr);
 
  template <typename OtherAccessor>
  explicit TriaIterator(const OtherAccessor &a);
 
  template <typename OtherAccessor>
  TriaIterator(const TriaIterator<OtherAccessor> &i);
 
  TriaIterator(const TriaAccessorBase<Accessor::structure_dimension,
                                      Accessor::dimension,
                                      Accessor::space_dimension> &tria_accessor,
               const typename Accessor::AccessorData *            local_data);
 
  template <typename OtherAccessor>
  TriaIterator(const TriaRawIterator<OtherAccessor> &i);
 
  template <typename OtherAccessor>
  TriaIterator(const TriaActiveIterator<OtherAccessor> &i);
 
  TriaIterator<Accessor> &
  operator=(const TriaIterator<Accessor> &);
 
  TriaIterator<Accessor> &
  operator=(const TriaRawIterator<Accessor> &);
 
  template <class OtherAccessor>
  TriaIterator<Accessor> &
  operator=(const TriaIterator<OtherAccessor> &);
 
  template <class OtherAccessor>
  TriaIterator<Accessor> &
  operator=(const TriaRawIterator<OtherAccessor> &);
 
  TriaIterator<Accessor> &
  operator++();
 
  TriaIterator<Accessor>
  operator++(int);
 
  TriaIterator<Accessor> &
  operator--();
 
  TriaIterator<Accessor>
  operator--(int);
  using iterator_category =
    typename TriaRawIterator<Accessor>::iterator_category;
  using value_type      = typename TriaRawIterator<Accessor>::value_type;
  using pointer         = typename TriaRawIterator<Accessor>::pointer;
  using reference       = typename TriaRawIterator<Accessor>::reference;
  using difference_type = typename TriaRawIterator<Accessor>::difference_type;
 
  DeclException0(ExcAssignmentOfUnusedObject);
};
 
 
template <typename Accessor>
class TriaActiveIterator : public TriaIterator<Accessor>
{
public:
  TriaActiveIterator();
 
  TriaActiveIterator(const TriaActiveIterator<Accessor> &);
 
  TriaActiveIterator(const TriaRawIterator<Accessor> &);
 
  TriaActiveIterator(const TriaIterator<Accessor> &);
 
  TriaActiveIterator(
    const Triangulation<Accessor::dimension, Accessor::space_dimension> *parent,
    const int                                                            level,
    const int                                                            index,
    const typename Accessor::AccessorData *local_data = nullptr);
 
  template <typename OtherAccessor>
  TriaActiveIterator(const TriaActiveIterator<OtherAccessor> &i);
 
  TriaActiveIterator(
    const TriaAccessorBase<Accessor::structure_dimension,
                           Accessor::dimension,
                           Accessor::space_dimension> &tria_accessor,
    const typename Accessor::AccessorData *            local_data);
 
  template <typename OtherAccessor>
  TriaActiveIterator(const TriaRawIterator<OtherAccessor> &i);
 
  TriaActiveIterator<Accessor> &
  operator=(const TriaActiveIterator<Accessor> &);
 
  TriaActiveIterator<Accessor> &
  operator=(const TriaIterator<Accessor> &);
 
  TriaActiveIterator<Accessor> &
  operator=(const TriaRawIterator<Accessor> &);
 
  template <class OtherAccessor>
  TriaActiveIterator<Accessor> &
  operator=(const TriaActiveIterator<OtherAccessor> &);
 
  template <class OtherAccessor>
  TriaActiveIterator<Accessor> &
  operator=(const TriaRawIterator<OtherAccessor> &);
 
  template <class OtherAccessor>
  TriaActiveIterator<Accessor> &
  operator=(const TriaIterator<OtherAccessor> &);
 
  TriaActiveIterator<Accessor> &
  operator++();
 
  TriaActiveIterator<Accessor>
  operator++(int);
 
  TriaActiveIterator<Accessor> &
  operator--();
 
  TriaActiveIterator<Accessor>
  operator--(int);
  using iterator_category = typename TriaIterator<Accessor>::iterator_category;
  using value_type        = typename TriaIterator<Accessor>::value_type;
  using pointer           = typename TriaIterator<Accessor>::pointer;
  using reference         = typename TriaIterator<Accessor>::reference;
  using difference_type   = typename TriaIterator<Accessor>::difference_type;
 
  DeclException0(ExcAssignmentOfInactiveObject);
};
 
 
/*----------------------- Inline functions -------------------*/
 
 
template <typename Accessor>
inline TriaRawIterator<Accessor>::TriaRawIterator(const Accessor &a)
  : accessor(a)
{}
 
 
 
template <typename Accessor>
template <typename OtherAccessor>
inline TriaRawIterator<Accessor>::TriaRawIterator(const OtherAccessor &a)
  : accessor(a)
{}
 
 
 
template <typename Accessor>
template <typename OtherAccessor>
inline TriaRawIterator<Accessor>::TriaRawIterator(
  const TriaRawIterator<OtherAccessor> &i)
  : accessor(i.accessor)
{}
 
 
 
template <typename Accessor>
template <typename OtherAccessor>
inline TriaRawIterator<Accessor>::TriaRawIterator(
  const TriaIterator<OtherAccessor> &i)
  : accessor(i.accessor)
{}
 
 
 
template <typename Accessor>
template <typename OtherAccessor>
inline TriaRawIterator<Accessor>::TriaRawIterator(
  const TriaActiveIterator<OtherAccessor> &i)
  : accessor(i.accessor)
{}
 
 
 
template <typename Accessor>
inline const Accessor &
TriaRawIterator<Accessor>::operator*() const
{
  Assert(Accessor::structure_dimension != Accessor::dimension ||
           state() == IteratorState::valid,
         ExcDereferenceInvalidCell(accessor));
  Assert(Accessor::structure_dimension == Accessor::dimension ||
           state() == IteratorState::valid,
         ExcDereferenceInvalidObject(accessor));
 
  return accessor;
}
 
 
 
template <typename Accessor>
inline Accessor &
TriaRawIterator<Accessor>::operator*()
{
  Assert(Accessor::structure_dimension != Accessor::dimension ||
           state() == IteratorState::valid,
         ExcDereferenceInvalidCell(accessor));
  Assert(Accessor::structure_dimension == Accessor::dimension ||
           state() == IteratorState::valid,
         ExcDereferenceInvalidObject(accessor));
 
  return accessor;
}
 
 
 
template <typename Accessor>
inline const Accessor &
TriaRawIterator<Accessor>::access_any() const
{
  return accessor;
}
 
 
 
template <typename Accessor>
inline const Accessor *
TriaRawIterator<Accessor>::operator->() const
{
  return &(this->operator*());
}
 
 
 
template <typename Accessor>
inline Accessor *
TriaRawIterator<Accessor>::operator->()
{
  return &(this->operator*());
}
 
 
 
template <typename Accessor>
inline IteratorState::IteratorStates
TriaRawIterator<Accessor>::state() const
{
  return accessor.state();
}
 
 
 
template <typename Accessor>
inline bool
TriaRawIterator<Accessor>::operator<(
  const TriaRawIterator<Accessor> &other) const
{
  Assert(state() != IteratorState::invalid,
         ExcDereferenceInvalidObject(accessor));
  Assert(other.state() != IteratorState::invalid,
         ExcDereferenceInvalidObject(other.accessor));
 
  Assert(&accessor.get_triangulation() == &other.accessor.get_triangulation(),
         ExcInvalidComparison());
 
  // Deal with iterators past end
  if (state() == IteratorState::past_the_end)
    return false;
  if (other.state() == IteratorState::past_the_end)
    return true;
 
  return ((**this) < (*other));
}
 
 
 
template <typename Accessor>
inline bool
TriaRawIterator<Accessor>::operator>(
  const TriaRawIterator<Accessor> &other) const
{
  return (other < *this);
}
 
 
 
template <typename Accessor>
inline TriaRawIterator<Accessor> &
TriaRawIterator<Accessor>::operator++()
{
  Assert(state() == IteratorState::valid, ExcAdvanceInvalidObject());
 
  ++accessor;
  return *this;
}
 
 
 
template <typename Accessor>
inline TriaRawIterator<Accessor> &
TriaRawIterator<Accessor>::operator--()
{
  Assert(state() == IteratorState::valid, ExcAdvanceInvalidObject());
 
  --accessor;
  return *this;
}
 
 
 
template <typename Accessor>
template <class StreamType>
inline void
TriaRawIterator<Accessor>::print(StreamType &out) const
{
  if (Accessor::structure_dimension == Accessor::dimension)
    out << accessor.level() << '.' << accessor.index();
  else
    out << accessor.index();
}
 
 
 
template <typename Accessor>
inline std::size_t
TriaRawIterator<Accessor>::memory_consumption() const
{
  return sizeof(TriaRawIterator<Accessor>);
}
 
 
 
template <typename Accessor>
template <typename OtherAccessor>
inline TriaIterator<Accessor>::TriaIterator(
  const TriaIterator<OtherAccessor> &i)
  : TriaRawIterator<Accessor>(i.accessor)
{}
 
 
 
template <typename Accessor>
template <typename OtherAccessor>
inline TriaIterator<Accessor>::TriaIterator(
  const TriaActiveIterator<OtherAccessor> &i)
  : TriaRawIterator<Accessor>(i.accessor)
{}
 
 
 
template <typename Accessor>
template <typename OtherAccessor>
inline TriaIterator<Accessor>::TriaIterator(
  const TriaRawIterator<OtherAccessor> &i)
  : TriaRawIterator<Accessor>(i.accessor)
{
#ifdef DEBUG
  // do this like this, because:
  // if we write
  // "Assert (IteratorState::past_the_end || used)"
  // used() is called anyway, even if
  // state==IteratorState::past_the_end, and will then
  // throw the exception!
  if (this->state() != IteratorState::past_the_end)
    Assert(this->accessor.used(), ExcAssignmentOfUnusedObject());
#endif
}
 
template <typename Accessor>
template <typename OtherAccessor>
TriaIterator<Accessor>::TriaIterator(const OtherAccessor &a)
  : TriaRawIterator<Accessor>(a)
{
#ifdef DEBUG
  // do this like this, because:
  // if we write
  // "Assert (IteratorState::past_the_end || used)"
  // used() is called anyway, even if
  // state==IteratorState::past_the_end, and will then
  // throw the exception!
  if (this->state() != IteratorState::past_the_end)
    Assert(this->accessor.used(), ExcAssignmentOfUnusedObject());
#endif
}
 
template <typename Accessor>
template <typename OtherAccessor>
inline TriaActiveIterator<Accessor>::TriaActiveIterator(
  const TriaActiveIterator<OtherAccessor> &i)
  : TriaIterator<Accessor>(i.accessor)
{}
 
 
 
template <typename Accessor>
template <typename OtherAccessor>
inline TriaActiveIterator<Accessor>::TriaActiveIterator(
  const TriaRawIterator<OtherAccessor> &i)
  : TriaIterator<Accessor>(i)
{
#ifdef DEBUG
  // do this like this, because:
  // if we write
  // "Assert (IteratorState::past_the_end || !has_children())"
  // has_children() is called anyway, even if
  // state==IteratorState::past_the_end, and will then
  // throw the exception!
  if (this->state() != IteratorState::past_the_end)
    Assert(this->accessor.has_children() == false,
           ExcAssignmentOfInactiveObject());
#endif
}
 
 
 
template <typename Accessor>
inline std::ostream &
operator<<(std::ostream &out, const TriaRawIterator<Accessor> &i)
{
  i.print(out);
  return out;
}
 
 
 
template <typename Accessor>
inline std::ostream &
operator<<(std::ostream &out, const TriaIterator<Accessor> &i)
{
  i.print(out);
  return out;
}
 
 
 
template <typename Accessor>
inline std::ostream &
operator<<(std::ostream &out, const TriaActiveIterator<Accessor> &i)
{
  i.print(out);
  return out;
}
 
 
DEAL_II_NAMESPACE_CLOSE
 
 
// if in optimized mode: include more templates
#ifndef DEBUG
#  include "tria_iterator.templates.h"
#endif
 
#endif