entitypointer.hh

Go to the documentation of this file.

// -*- tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
// vi: set et ts=4 sw=2 sts=2:
#ifndef DUNE_GRID_ENTITYPOINTER_HH
#define DUNE_GRID_ENTITYPOINTER_HH
 
#include <utility>
 
#include <dune/common/proxymemberaccess.hh>
#include <dune/common/iteratorfacades.hh>
#include <dune/common/deprecated.hh>
#include <dune/grid/common/grid.hh>
 
#define DUNE_ENTITYPOINTER_DEPRECATED_MSG  DUNE_DEPRECATED_MSG("EntityPointer is deprecated and will be removed after the release of dune-grid-2.4. Instead, you can copy and store entities directly now. Note, this might lead to a decreased performance until all grid implementations properly addressed this interface change.")
namespace Dune
{
 
  // External forward declaration
  // ----------------------------
 
  template< int, int, class, template< int, int, class > class >
  class Entity;
 
 
 
  template<class GridImp, class IteratorImp>
  class EntityPointer
  {
    // need to make copy constructor of EntityPointer work for any iterator
    //friend class EntityPointer<GridImp,typename IteratorImp::EntityPointerImp>;
    template< class, class > friend class EntityPointer;
 
#if DUNE_GRID_EXPERIMENTAL_GRID_EXTENSIONS
  public:
#else
  protected:
    // give the GridDefaultImplementation class access to the realImp
    friend class GridDefaultImplementation<
        GridImp::dimension, GridImp::dimensionworld,
        typename GridImp::ctype,
        typename GridImp::GridFamily> ;
#endif
    // type of underlying implementation, for internal use only
    typedef IteratorImp Implementation;
 
    Implementation &impl () { return realIterator; }
    const Implementation &impl () const { return realIterator; }
 
  protected:
    Implementation realIterator;
 
  public:
    enum { codimension = IteratorImp::codimension };
 
    typedef typename IteratorImp::Entity Entity;
 
    typedef typename std::conditional<
      std::is_lvalue_reference<
        decltype(realIterator.dereference())
        >::value,
      const Entity&,
      Entity
      >::type Reference;
 
    //===========================================================
    //===========================================================
 
    template< class ItImp >
    explicit EntityPointer ( const EntityPointer< GridImp, ItImp > &ep )
      : realIterator( ep.realIterator )
    {}
 
    EntityPointer()
    {}
 
    DUNE_ENTITYPOINTER_DEPRECATED_MSG
    EntityPointer(const Entity& entity)
      : realIterator( entity.impl() )
    {}
 
    EntityPointer ( const typename Entity::Implementation &entityImp )
      : realIterator( entityImp )
    {}
 
    template< class ItImp >
    DUNE_ENTITYPOINTER_DEPRECATED_MSG
    inline EntityPointer & operator= ( const EntityPointer< GridImp, ItImp > &ep )
    {
      realIterator = ep.realIterator;
      return *this;
    }
 
 
    //===========================================================
    //===========================================================
 
    // The behavior when dereferencing the EntityPointer facade depends on
    // the way the grid implementation handles returning entities. The implementation
    // may either return a reference to an entity stored inside the EntityPointer
    // implementation or a temporary Entity object. This object has to be forwarded through
    // the facade to the user, which requires a little trickery, especially for operator->().
    //
    // In order to avoid confusing users reading the Doxygen documentation, we provide "clean"
    // function signatures to Doxygen and hide the actual implementations.
 
#ifdef DOXYGEN
 
    Entity operator*() const
    DUNE_ENTITYPOINTER_DEPRECATED_MSG;
 
 
    const Entity* operator->() const
    DUNE_ENTITYPOINTER_DEPRECATED_MSG;
 
#else // DOXYGEN
 
    Reference
    operator*() const
    DUNE_ENTITYPOINTER_DEPRECATED_MSG
    {
      return realIterator.dereference();
    }
 
    decltype(handle_proxy_member_access(realIterator.dereference()))
    operator->() const
    DUNE_ENTITYPOINTER_DEPRECATED_MSG
    {
      return handle_proxy_member_access(realIterator.dereference());
    }
 
    template<typename T>
    // this construction, where the deprecation warning is triggered by a separate function,
    // is slightly convoluted, but I could not get the warning to trigger reliably when attached
    // directly to the cast operator.
    DUNE_DEPRECATED_MSG("The implicit cast from EntityPointer to an Entity reference is DANGEROUS. It's mainly there for writing backwards compatible code that doesn't trigger a deprecation warning for ported grids and must ONLY be used if the returned reference is used in an rvalue-like setting!")
    void trigger_entity_cast_warning() const
    {}
 
    template<typename T, typename std::enable_if<std::is_same<T,Entity>::value,int>::type = 0>
    operator const T&() const
    {
      static_assert(std::is_same<T,Entity>::value,"invalid cast");
      trigger_entity_cast_warning<T>();
      return realIterator.dereference();
    }
 
#endif // DOXYGEN
 
 
    //===========================================================
    //===========================================================
 
    template< class ItImp >
    bool operator== ( const EntityPointer< GridImp, ItImp > &rhs ) const
    {
      return equals( rhs );
    }
 
    template< class ItImp >
    bool operator!= ( const EntityPointer< GridImp, ItImp > &rhs ) const
    {
      return !equals( rhs );
    }
 
    DUNE_ENTITYPOINTER_DEPRECATED_MSG
    bool operator==(const Entity& rhs) const
    {
      return (**this) == rhs;
    }
 
    DUNE_ENTITYPOINTER_DEPRECATED_MSG
    bool operator!=(const Entity& rhs) const
    {
      return (**this) != rhs;
    }
 
 
    //===========================================================
    //===========================================================
 
    int level () const
    DUNE_ENTITYPOINTER_DEPRECATED_MSG
    {
      return realIterator.level();
    }
 
 
 
    //===========================================================
    //===========================================================
 
    EntityPointer(const IteratorImp & i) :
      realIterator(i) {}
 
    template< class ItImp >
    bool equals ( const EntityPointer< GridImp, ItImp > &rhs ) const
    {
      return realIterator.equals( rhs.realIterator );
    }
 
    //===========================================================
    //===========================================================
 
    typedef typename GridImp::template Codim<codimension>::Geometry Geometry;
 
    typedef typename GridImp::template Codim<codimension>::EntitySeed EntitySeed;
 
    typedef typename GridImp::template Codim<codimension>::LocalGeometry LocalGeometry;
 
    template <int cd>
    struct Codim
    {
      typedef typename GridImp::template Codim<cd>::EntityPointer EntityPointer;
      typedef typename GridImp::template Codim<cd>::Entity Entity;
    };
 
    // typedef typename Entity::EntityPointer EntityPointer;
 
    typedef typename GridImp::HierarchicIterator HierarchicIterator;
 
    enum {
      dimension=Entity::dimension
    };
    enum {
      mydimension=Entity::dimension
    };
 
    PartitionType partitionType () const { return realIterator.dereference().partitionType(); }
 
    Geometry geometry () const { return realIterator.dereference().geometry(); }
 
    GeometryType type () const { return realIterator.dereference().type(); }
 
    EntitySeed seed () const { return realIterator.dereference().seed(); }
 
#define CHECK_CODIM0 int ecodim = codimension, typename std::enable_if<ecodim == 0,int>::type = 0
#define ONLY_CODIM0 template<int ecodim = codimension, typename std::enable_if<ecodim == 0,int>::type = 0>
 
    template< int codim, CHECK_CODIM0 >
    typename Codim<codim>::Entity
    subEntity ( int i ) const
    {
      return realIterator.dereference().template subEntity< codim >(i);
    }
 
    ONLY_CODIM0
    bool hasFather () const
    {
      return realIterator.dereference().hasFather();
    }
 
    ONLY_CODIM0
    bool isLeaf () const
    {
      return realIterator.dereference().isLeaf();
    }
 
    ONLY_CODIM0
    bool isRegular() const { return realIterator.dereference().isRegular(); }
 
    ONLY_CODIM0
    LocalGeometry geometryInFather () const { return realIterator.dereference().geometryInFather(); }
 
    ONLY_CODIM0
    HierarchicIterator hbegin (int maxLevel) const
    {
      return realIterator.dereference().hbegin(maxLevel);
    }
 
    ONLY_CODIM0
    HierarchicIterator hend (int maxLevel) const
    {
      return realIterator.dereference().hend(maxLevel);
    }
 
    ONLY_CODIM0
    bool isNew () const { return realIterator.dereference().isNew(); }
 
    ONLY_CODIM0
    bool mightVanish () const { return realIterator.dereference().mightVanish(); }
 
    ONLY_CODIM0
    bool hasBoundaryIntersections () const { return realIterator.dereference().hasBoundaryIntersections(); }
 
  };
 
 
 
#ifndef DOXYEN
 
  // DefaultEntityPointer
  // --------------------
 
  /* The EntityPointer class defined above has been deprecated. Unitil its
     final removal valid Dune grids still have to provide at least a suitable
     EntityPointer typedef. This class provides a default implementation of an
     entity pointer from a given Dune::Entity type:
     \code
     struct GridFamily
     {
       ...
       typedef ImplementationDefined Entity;
       typedef DefaultEntityPointer<Entity> EntityPointer;
       ...
     };
     \endcode
 
     This class will retain a possible compatibility support with the
     deprecated interface behavior if the iterator classes in the grid
     implementation provide the following two additional methods:
     \code
     class Iterator
     {
       // dereference() method required by Dune::EntityIterator
       typedef ImplemenatationDefined Entity;
       Entity dereference () const;
 
       // allow for (deprecated) construction/assignment of EntityPointer from a given iterator
       operator Dune::DefaultEntityPointer<Entity>() const
       {
         return Dune::DefaultEntityPointer<Entity>(dereference());
       }
 
       // allow for (deprecated) comparison of an iterator with an entity pointer
       bool equals(const Dune::DefaultEntityPointer<Entity> &rhs) const
       {
         return dereference() == rhs.dereference();
       }
     };
     \endcode
  */
  template< class E >
  class DefaultEntityPointer;
 
  template< int codim, int dim, class Grid, template< int, int, class > class EntityImp >
  class DefaultEntityPointer< Dune::Entity< codim, dim, Grid, EntityImp > >
  {
  public:
    static const int codimension = codim;
 
    typedef Dune::Entity< codim, dim, Grid, EntityImp > Entity;
 
    DefaultEntityPointer () {}
 
    explicit DefaultEntityPointer ( Entity entity )
      : entity_( std::move( entity ) )
    {}
 
    explicit DefaultEntityPointer ( EntityImp< codim, dim, Grid > entity )
      : entity_( std::move( entity ) )
    {}
 
    const Entity &dereference () const { return entity_; }
 
    bool equals ( const DefaultEntityPointer &rhs ) const
    {
      return entity_ == rhs.entity_;
    }
 
    int level () const { return entity_.level(); }
 
  private:
    Entity entity_;
  };
 
#endif // #ifndef DOXYEN
 
}
#undef DUNE_ENTITYPOINTER_DEPRECATED_MSG
 
#endif // DUNE_GRID_ENTITYPOINTER_HH