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 at
// the top level of the deal.II distribution.
//
// ---------------------------------------------------------------------

#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:
  typedef Accessor AccessorType;

  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;

  typedef std::bidirectional_iterator_tag iterator_category;
  typedef Accessor                        value_type;
  typedef int                             difference_type;
  typedef Accessor                       *pointer;
  typedef Accessor                       &reference;

  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);
  typedef typename TriaRawIterator<Accessor>::iterator_category iterator_category;
  typedef typename TriaRawIterator<Accessor>::value_type        value_type;
  typedef typename TriaRawIterator<Accessor>::pointer           pointer;
  typedef typename TriaRawIterator<Accessor>::reference         reference;
  typedef typename TriaRawIterator<Accessor>::difference_type   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);
  typedef typename TriaIterator<Accessor>::iterator_category iterator_category;
  typedef typename TriaIterator<Accessor>::value_type        value_type;
  typedef typename TriaIterator<Accessor>::pointer           pointer;
  typedef typename TriaIterator<Accessor>::reference         reference;
  typedef typename TriaIterator<Accessor>::difference_type   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     ---------------------------*/