tria_iterator.h

// ---------------------------------------------------------------------
//
// Copyright (C) 1998 - 2018 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


/*----------------------------   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

template <int dim, int spacedim>
class Triangulation;
template <int, int, int>
class TriaAccessorBase;

template <typename>
class TriaIterator;
template <typename>
class TriaActiveIterator;



// 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 &);

  bool
  operator==(const TriaRawIterator &) 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;


  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 = 0);

  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


/*----------------------------   tria-iterator.h ---------------------------*/
#endif
/*----------------------------   tria-iterator.h ---------------------------*/