dune-grid  3.0-git
common/entitypointer.hh
Go to the documentation of this file.
1 // -*- tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
2 // vi: set et ts=4 sw=2 sts=2:
3 #ifndef DUNE_GRID_ENTITYPOINTER_HH
4 #define DUNE_GRID_ENTITYPOINTER_HH
5 
6 #include <utility>
7 
8 #include <dune/common/proxymemberaccess.hh>
9 #include <dune/common/iteratorfacades.hh>
10 #include <dune/common/deprecated.hh>
11 #include <dune/geometry/type.hh>
13 
18 #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.")
19 namespace Dune
20 {
21 
22  // External forward declaration
23  // ----------------------------
24 
25  template< int, int, class, template< int, int, class > class >
26  class Entity;
27 
28 
29 
112  template<class GridImp, class IteratorImp>
114  {
115  // need to make copy constructor of EntityPointer work for any iterator
116  //friend class EntityPointer<GridImp,typename IteratorImp::EntityPointerImp>;
117  template< class, class > friend class EntityPointer;
118 
119 #if DUNE_GRID_EXPERIMENTAL_GRID_EXTENSIONS
120  public:
121 #else
122  protected:
123  // give the GridDefaultImplementation class access to the realImp
124  friend class GridDefaultImplementation<
125  GridImp::dimension, GridImp::dimensionworld,
126  typename GridImp::ctype,
127  typename GridImp::GridFamily> ;
128 #endif
129  // type of underlying implementation, for internal use only
130  typedef IteratorImp Implementation;
131 
135  const Implementation &impl () const { return realIterator; }
136 
137  protected:
139 
140  public:
142  enum { codimension = IteratorImp::codimension };
143 
145  typedef typename IteratorImp::Entity Entity;
146 
148  typedef typename std::conditional<
149  std::is_lvalue_reference<
150  decltype(realIterator.dereference())
151  >::value,
152  const Entity&,
153  Entity
155 
156  //===========================================================
160  //===========================================================
161 
168  template< class ItImp >
170  : realIterator( ep.realIterator )
171  {}
172 
175  {}
176 
184  EntityPointer(const Entity& entity)
185  : realIterator( entity.impl() )
186  {}
187 
193  EntityPointer ( const typename Entity::Implementation &entityImp )
194  : realIterator( entityImp )
195  {}
196 
197  template< class ItImp >
200  {
202  return *this;
203  }
204 
206 
207  //===========================================================
211  //===========================================================
212 
213  // The behavior when dereferencing the EntityPointer facade depends on
214  // the way the grid implementation handles returning entities. The implementation
215  // may either return a reference to an entity stored inside the EntityPointer
216  // implementation or a temporary Entity object. This object has to be forwarded through
217  // the facade to the user, which requires a little trickery, especially for operator->().
218  //
219  // In order to avoid confusing users reading the Doxygen documentation, we provide "clean"
220  // function signatures to Doxygen and hide the actual implementations.
221 
222 #ifdef DOXYGEN
223 
225  Entity operator*() const
227 
228 
230  const Entity* operator->() const
232 
233 #else // DOXYGEN
234 
236  Reference
237  operator*() const
239  {
240  return realIterator.dereference();
241  }
242 
244  decltype(handle_proxy_member_access(realIterator.dereference()))
245  operator->() const
247  {
248  return handle_proxy_member_access(realIterator.dereference());
249  }
250 
251  template<typename T>
252  // this construction, where the deprecation warning is triggered by a separate function,
253  // is slightly convoluted, but I could not get the warning to trigger reliably when attached
254  // directly to the cast operator.
255  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!")
256  void trigger_entity_cast_warning() const
257  {}
258 
259  template<typename T, typename std::enable_if<std::is_same<T,Entity>::value,int>::type = 0>
260  operator const T&() const
261  {
262  static_assert(std::is_same<T,Entity>::value,"invalid cast");
263  trigger_entity_cast_warning<T>();
264  return realIterator.dereference();
265  }
266 
267 #endif // DOXYGEN
268 
270 
271  //===========================================================
275  //===========================================================
276 
282  template< class ItImp >
284  {
285  return equals( rhs );
286  }
287 
293  template< class ItImp >
295  {
296  return !equals( rhs );
297  }
299 
306  bool operator==(const Entity& rhs) const
307  {
308  return (**this) == rhs;
309  }
310 
317  bool operator!=(const Entity& rhs) const
318  {
319  return (**this) != rhs;
320  }
321 
322 
323  //===========================================================
327  //===========================================================
328 
338  int level () const
340  {
341  return realIterator.level();
342  }
343 
345 
346 
347  //===========================================================
351  //===========================================================
352 
358  EntityPointer(const IteratorImp & i) :
359  realIterator(i) {}
360 
362  template< class ItImp >
363  bool equals ( const EntityPointer< GridImp, ItImp > &rhs ) const
364  {
365  return realIterator.equals( rhs.realIterator );
366  }
368 
369  //===========================================================
373  //===========================================================
374 
376  typedef typename GridImp::template Codim<codimension>::Geometry Geometry;
377 
379  typedef typename GridImp::template Codim<codimension>::EntitySeed EntitySeed;
380 
388  typedef typename GridImp::template Codim<codimension>::LocalGeometry LocalGeometry;
389 
391  template <int cd>
392  struct Codim
393  {
394  typedef typename GridImp::template Codim<cd>::EntityPointer EntityPointer;
395  typedef typename GridImp::template Codim<cd>::Entity Entity;
396  };
397 
399  // typedef typename Entity::EntityPointer EntityPointer;
400 
402  typedef typename GridImp::HierarchicIterator HierarchicIterator;
403 
404  enum {
407  };
408  enum {
411  };
412 
414  PartitionType partitionType () const { return realIterator.dereference().partitionType(); }
415 
428  Geometry geometry () const { return realIterator.dereference().geometry(); }
429 
433  GeometryType type () const { return realIterator.dereference().type(); }
434 
438  EntitySeed seed () const { return realIterator.dereference().seed(); }
439 
440 #define CHECK_CODIM0 int ecodim = codimension, typename std::enable_if<ecodim == 0,int>::type = 0
441 #define ONLY_CODIM0 template<int ecodim = codimension, typename std::enable_if<ecodim == 0,int>::type = 0>
442 
443  template< int codim, CHECK_CODIM0 >
444  typename Codim<codim>::Entity
445  subEntity ( int i ) const
446  {
447  return realIterator.dereference().template subEntity< codim >(i);
448  }
449 
454  bool hasFather () const
455  {
456  return realIterator.dereference().hasFather();
457  }
458 
461  bool isLeaf () const
462  {
463  return realIterator.dereference().isLeaf();
464  }
465 
470  bool isRegular() const { return realIterator.dereference().isRegular(); }
471 
498  LocalGeometry geometryInFather () const { return realIterator.dereference().geometryInFather(); }
499 
512  HierarchicIterator hbegin (int maxLevel) const
513  {
514  return realIterator.dereference().hbegin(maxLevel);
515  }
516 
525  HierarchicIterator hend (int maxLevel) const
526  {
527  return realIterator.dereference().hend(maxLevel);
528  }
529 
533  bool isNew () const { return realIterator.dereference().isNew(); }
534 
540  bool mightVanish () const { return realIterator.dereference().mightVanish(); }
541 
545  bool hasBoundaryIntersections () const { return realIterator.dereference().hasBoundaryIntersections(); }
547 
548  };
549 
550 
551 
552 #ifndef DOXYEN
553 
554  // DefaultEntityPointer
555  // --------------------
556 
557  /* The EntityPointer class defined above has been deprecated. Unitil its
558  final removal valid Dune grids still have to provide at least a suitable
559  EntityPointer typedef. This class provides a default implementation of an
560  entity pointer from a given Dune::Entity type:
561  \code
562  struct GridFamily
563  {
564  ...
565  typedef ImplementationDefined Entity;
566  typedef DefaultEntityPointer<Entity> EntityPointer;
567  ...
568  };
569  \endcode
570 
571  This class will retain a possible compatibility support with the
572  deprecated interface behavior if the iterator classes in the grid
573  implementation provide the following two additional methods:
574  \code
575  class Iterator
576  {
577  // dereference() method required by Dune::EntityIterator
578  typedef ImplemenatationDefined Entity;
579  Entity dereference () const;
580 
581  // allow for (deprecated) construction/assignment of EntityPointer from a given iterator
582  operator Dune::DefaultEntityPointer<Entity>() const
583  {
584  return Dune::DefaultEntityPointer<Entity>(dereference());
585  }
586 
587  // allow for (deprecated) comparison of an iterator with an entity pointer
588  bool equals(const Dune::DefaultEntityPointer<Entity> &rhs) const
589  {
590  return dereference() == rhs.dereference();
591  }
592  };
593  \endcode
594  */
595  template< class E >
597 
598  template< int codim, int dim, class Grid, template< int, int, class > class EntityImp >
599  class DefaultEntityPointer< Dune::Entity< codim, dim, Grid, EntityImp > >
600  {
601  public:
602  static const int codimension = codim;
603 
605 
607 
608  explicit DefaultEntityPointer ( Entity entity )
609  : entity_( std::move( entity ) )
610  {}
611 
612  explicit DefaultEntityPointer ( EntityImp< codim, dim, Grid > entity )
613  : entity_( std::move( entity ) )
614  {}
615 
616  const Entity &dereference () const { return entity_; }
617 
618  bool equals ( const DefaultEntityPointer &rhs ) const
619  {
620  return entity_ == rhs.entity_;
621  }
622 
623  int level () const { return entity_.level(); }
624 
625  private:
626  Entity entity_;
627  };
628 
629 #endif // #ifndef DOXYEN
630 
631 }
632 #undef DUNE_ENTITYPOINTER_DEPRECATED_MSG
633 
634 #endif // DUNE_GRID_ENTITYPOINTER_HH
Dune::EntityPointer::equals
bool equals(const EntityPointer< GridImp, ItImp > &rhs) const
Forward equality check to realIterator.
Definition: common/entitypointer.hh:363
Dune::EntityPointer::EntityPointer
DUNE_ENTITYPOINTER_DEPRECATED_MSG EntityPointer(const Entity &entity)
Templatized constructor from type of entity that this entity pointer points to. This constructor can ...
Definition: common/entitypointer.hh:184
Dune::DefaultEntityPointer< Dune::Entity< codim, dim, Grid, EntityImp > >::dereference
const Entity & dereference() const
Definition: common/entitypointer.hh:616
Dune::DefaultEntityPointer
Definition: common/entitypointer.hh:596
Dune
Include standard header files.
Definition: agrid.hh:59
Dune::EntityPointer::geometryInFather
ONLY_CODIM0 LocalGeometry geometryInFather() const
Provides information how this element has been subdivided from its father element.
Definition: common/entitypointer.hh:498
Dune::EntityPointer::isNew
ONLY_CODIM0 bool isNew() const
Returns true, if the entity has been created during the last call to adapt()
Definition: common/entitypointer.hh:533
Dune::EntityPointer::type
GeometryType type() const
Return the name of the reference element. The type can be used to access the Dune::ReferenceElement.
Definition: common/entitypointer.hh:433
Dune::EntityPointer::isLeaf
ONLY_CODIM0 bool isLeaf() const
Returns true if the entity is contained in the leaf grid.
Definition: common/entitypointer.hh:461
Dune::EntityPointer::mydimension
Know dimension of the entity.
Definition: common/entitypointer.hh:410
Dune::EntityPointer::hasFather
ONLY_CODIM0 bool hasFather() const
Return true if entity has a father entity which can be accessed using the father() method.
Definition: common/entitypointer.hh:454
Dune::EntityPointer::Geometry
GridImp::template Codim< codimension >::Geometry Geometry
The geometry type of this entity.
Definition: common/entitypointer.hh:376
Dune::Entity::Implementation
EntityImp< cd, dim, GridImp > Implementation
Definition: common/entity.hh:78
Dune::EntityPointer< Grid, IteratorImp >::Implementation
IteratorImp Implementation
Definition: common/entitypointer.hh:130
Dune::EntityPointer::operator!=
bool operator!=(const EntityPointer< GridImp, ItImp > &rhs) const
Checks for inequality. Only works for EntityPointers and iterators on the same grid....
Definition: common/entitypointer.hh:294
Dune::EntityPointer::seed
EntitySeed seed() const
Return the entity seed which contains sufficient information to generate the entity again and uses as...
Definition: common/entitypointer.hh:438
Dune::EntityPointer::realIterator
Implementation realIterator
Definition: common/entitypointer.hh:138
Dune::EntityPointer::operator!=
DUNE_ENTITYPOINTER_DEPRECATED_MSG bool operator!=(const Entity &rhs) const
Compares an EntityPointer with an Entity for inequality.
Definition: common/entitypointer.hh:317
Dune::EntityPointer::LocalGeometry
GridImp::template Codim< codimension >::LocalGeometry LocalGeometry
The geometry type of this entity when the geometry is expressed embedded in the father element.
Definition: common/entitypointer.hh:388
Dune::PartitionType
PartitionType
Attributes used in the generic overlap model.
Definition: gridenums.hh:28
Dune::VTK::GeometryType
GeometryType
Type representing VTK's entity geometry types.
Definition: common.hh:178
Dune::DefaultEntityPointer< Dune::Entity< codim, dim, Grid, EntityImp > >::DefaultEntityPointer
DefaultEntityPointer(EntityImp< codim, dim, Grid > entity)
Definition: common/entitypointer.hh:612
gridenums.hh
Dune::EntityPointer::hbegin
ONLY_CODIM0 HierarchicIterator hbegin(int maxLevel) const
Inter-level access to elements that resulted from (recursive) subdivision of this element.
Definition: common/entitypointer.hh:512
Dune::DefaultEntityPointer< Dune::Entity< codim, dim, Grid, EntityImp > >::DefaultEntityPointer
DefaultEntityPointer(Entity entity)
Definition: common/entitypointer.hh:608
Dune::Entity
Wrapper class for entities.
Definition: common/entity.hh:61
Dune::EntityPointer::EntitySeed
GridImp::template Codim< codimension >::EntitySeed EntitySeed
The corresponding entity seed (for storage of entities)
Definition: common/entitypointer.hh:379
Dune::EntityPointer::codimension
Definition: common/entitypointer.hh:142
Dune::EntityPointer::geometry
Geometry geometry() const
obtain geometric realization of the entity
Definition: common/entitypointer.hh:428
Dune::EntityPointer::hend
ONLY_CODIM0 HierarchicIterator hend(int maxLevel) const
Returns iterator to one past the last son element.
Definition: common/entitypointer.hh:525
DUNE_ENTITYPOINTER_DEPRECATED_MSG
#define DUNE_ENTITYPOINTER_DEPRECATED_MSG
Definition: common/entitypointer.hh:18
Dune::EntityPointer::hasBoundaryIntersections
ONLY_CODIM0 bool hasBoundaryIntersections() const
Returns true, if entity has intersections with boundary.
Definition: common/entitypointer.hh:545
Dune::DefaultEntityPointer< Dune::Entity< codim, dim, Grid, EntityImp > >::DefaultEntityPointer
DefaultEntityPointer()
Definition: common/entitypointer.hh:606
Dune::EntityPointer::impl
const Implementation & impl() const
return reference to the real implementation
Definition: common/entitypointer.hh:135
Dune::EntityPointer::Codim::EntityPointer
GridImp::template Codim< cd >::EntityPointer EntityPointer
Definition: common/entitypointer.hh:394
Dune::EntityPointer::Codim::Entity
GridImp::template Codim< cd >::Entity Entity
Definition: common/entitypointer.hh:395
Dune::DefaultEntityPointer< Dune::Entity< codim, dim, Grid, EntityImp > >::Entity
Dune::Entity< codim, dim, Grid, EntityImp > Entity
Definition: common/entitypointer.hh:604
ONLY_CODIM0
#define ONLY_CODIM0
Definition: common/entitypointer.hh:441
Dune::EntityPointer::impl
Implementation & impl()
return reference to the real implementation
Definition: common/entitypointer.hh:133
Dune::EntityPointer::isRegular
ONLY_CODIM0 bool isRegular() const
Returns true if element is of regular type in red/green type refinement. In bisection or hanging node...
Definition: common/entitypointer.hh:470
Dune::EntityPointer::level
int level() const DUNE_ENTITYPOINTER_DEPRECATED_MSG
Ask for level of entity.
Definition: common/entitypointer.hh:338
Dune::EntityPointer::EntityPointer
EntityPointer(const EntityPointer< GridImp, ItImp > &ep)
Templatized copy constructor from arbitrary IteratorImp. This enables that an EntityPointer can be co...
Definition: common/entitypointer.hh:169
Dune::GridDefaultImplementation
Definition: common/geometry.hh:24
Dune::EntityPointer::Codim
EntityPointer types of the different codimensions.
Definition: common/entitypointer.hh:392
Dune::EntityPointer::EntityPointer
EntityPointer(const typename Entity::Implementation &entityImp)
Constructor from type of entity implementation that this entity pointer points to....
Definition: common/entitypointer.hh:193
Dune::EntityPointer::HierarchicIterator
GridImp::HierarchicIterator HierarchicIterator
The codim==0 EntityPointer type.
Definition: common/entitypointer.hh:402
Dune::DefaultEntityPointer< Dune::Entity< codim, dim, Grid, EntityImp > >::level
int level() const
Definition: common/entitypointer.hh:623
Dune::EntityPointer::partitionType
PartitionType partitionType() const
Partition type of this entity.
Definition: common/entitypointer.hh:414
Dune::EntityPointer::subEntity
Codim< codim >::Entity subEntity(int i) const
Definition: common/entitypointer.hh:445
Dune::EntityPointer::operator==
bool operator==(const EntityPointer< GridImp, ItImp > &rhs) const
Checks for equality. Only works for EntityPointers and iterators on the same grid....
Definition: common/entitypointer.hh:283
Dune::EntityPointer::operator==
DUNE_ENTITYPOINTER_DEPRECATED_MSG bool operator==(const Entity &rhs) const
Compares an EntityPointer with an Entity for equality.
Definition: common/entitypointer.hh:306
Dune::EntityPointer< Grid, IteratorImp >::Reference
std::conditional< std::is_lvalue_reference< decltype(realIterator.dereference()) >::value, const Entity &, Entity >::type Reference
Tpy of the reference used when derefencing the Ptr.
Definition: common/entitypointer.hh:154
Dune::EntityPointer::operator*
Entity operator*() const DUNE_ENTITYPOINTER_DEPRECATED_MSG
Dereferencing operator.
Dune::EntityPointer::EntityPointer
EntityPointer(const IteratorImp &i)
Copy Constructor from an Iterator implementation.
Definition: common/entitypointer.hh:358
Dune::EntityPointer::operator=
DUNE_ENTITYPOINTER_DEPRECATED_MSG EntityPointer & operator=(const EntityPointer< GridImp, ItImp > &ep)
Definition: common/entitypointer.hh:199
Dune::EntityPointer::dimension
Know the grid's dimension.
Definition: common/entitypointer.hh:406
Dune::DefaultEntityPointer< Dune::Entity< codim, dim, Grid, EntityImp > >::equals
bool equals(const DefaultEntityPointer &rhs) const
Definition: common/entitypointer.hh:618
Dune::Entity::dimension
Know the grid dimension.
Definition: common/entity.hh:108
Dune::EntityPointer::EntityPointer
EntityPointer()
Default constructor of an empty (undefined) EntityPointer.
Definition: common/entitypointer.hh:174
Dune::EntityPointer::Entity
IteratorImp::Entity Entity
The Entity that this EntityPointer can point to.
Definition: common/entitypointer.hh:145
Dune::EntityPointer::mightVanish
ONLY_CODIM0 bool mightVanish() const
Returns true, if entity might disappear during the next call to adapt(). If the method returns false,...
Definition: common/entitypointer.hh:540
Dune::EntityPointer
Wrapper class for pointers to entities.
Definition: common/entitypointer.hh:113