Dune::IteratorFacade< It, C, V, R, P, D > Class Template Reference

CRTP-Mixing class for stl conformant iterators of given iterator category. More...

#include <dune/common/iteratorfacades.hh>

Public Member Functions
constexpr decltype(auto)	operator* () const
	Dereferencing operator.
constexpr pointer	operator-> () const
	Arrow access to members of referenced value.
constexpr decltype(auto)	operator++ ()
	Preincrement operator.
constexpr DerivedIterator	operator++ (int)
	Postincrement operator.
template<bool dummy = true, std::enable_if_t< isBidirectional and dummy, int > = 0>
constexpr decltype(auto)	operator-- ()
	Predecrement operator. More...
template<bool dummy = true, std::enable_if_t< isBidirectional and dummy, int > = 0>
constexpr DerivedIterator	operator-- (int)
	Postdecrement operator. More...
template<bool dummy = true, std::enable_if_t< isRandomAccess and dummy, int > = 0>
constexpr reference	operator[] (difference_type n) const
	Dereference element with given offset form this iterator. More...
template<bool dummy = true, std::enable_if_t< isRandomAccess and dummy, int > = 0>
constexpr decltype(auto)	operator+= (difference_type n)
	Increment iterator by given value. More...
template<bool dummy = true, std::enable_if_t< isRandomAccess and dummy, int > = 0>
constexpr DerivedIterator	operator+ (difference_type n) const
	Create iterator incremented by given value. More...
template<bool dummy = true, std::enable_if_t< isRandomAccess and dummy, int > = 0>
constexpr DerivedIterator &	operator-= (difference_type n)
	Decrement iterator by given value. More...
template<bool dummy = true, std::enable_if_t< isRandomAccess and dummy, int > = 0>
constexpr DerivedIterator	operator- (difference_type n) const
	Create iterator decremented by given value. More...

Protected Types
using	DerivedIterator = It
	The derived iterator type.

Protected Member Functions
constexpr const DerivedIterator &	derived () const
	Cast of *this to const DerivedIterator type.
constexpr DerivedIterator &	derived ()
	Cast of *this to DerivedIterator type.

Detailed Description

template<class It, class C, class V, class R = V&, class P = V*, class D = std::ptrdiff_t>
class Dune::IteratorFacade< It, C, V, R, P, D >

CRTP-Mixing class for stl conformant iterators of given iterator category.

The iterator category is given by the corresponding tag class. Currently supported tags are std::forward_iterator_tag, std::bidirectional_iterator_tag, std::random_access_iterator_tag.

For proxy iterators (i.e. iterator that don't return a real reference but a so called proxy-value that behaves like a reference), the template parameter R should be the type of the proxy-value and no reference. In the latter case one should also use P=ProxyArrowResult<R> as pointer type used as return value of operator->. If P is not a raw pointer type, then it must be constructable from V.

The derived class should implement methods as documented in the following. Notice that, if the iterator provides multiple of the possible implementations for a certain feature, then precedence for the different implementation follows the order given below.

For a forward iterator the derived class It must provide:

• Dereferencing a const iterator using any of the following approaches:
  1. implement *it
  2. implement *(it.baseIterator())
• Incrementing a non-const iterator using any of the following approaches:
  1. implement ++it
  2. implement ++(it.baseIterator())
  3. implement it+=1
• Equality comparison of two const iterators using any of the following approaches:
  1. implement it1==it2
  2. implement it1.baseIterator()==it2.baseIterator()

For a bidirectional iterator it must additionally provide:

• Decrementing a non-const iterator using any of the following approaches:
  1. implement --it
  2. implement --(it.baseIterator())
  3. implement it-=1

For a random access iterator it must additionally provide:

• Advacing a non-const iterator by an offset using any of the following approaches:
  1. implement it+=n
  2. implement it.baseIterator()+=n
• Computing the distance between two const iterators using any of the following approaches:
  1. implement it1-it2
  2. implement it1.baseIterator()-it2.baseIterator()

When relying on option 2 for any of those features, the it.baseIterator() method can be made private to hide it from the user. Then the derived class must declare IteratorFacadeAccess as friend. Notice that depending on the feature it is used for, it.baseIterator() must be a const or non-const method. Thus the derived class must provide both versions if it wants to implement const and non-const operation in terms of `it.baseIterator().

For example a forward iterator for values of type V could be implemented by providing the core operations manually (option 1 above):

class FooIterator
  : public Dune::IteratorFacade<FooIterator, std::forward_iterator_tag, V>
{
  using Facade = Dune::IteratorFacade<FooIterator, std::forward_iterator_tag, V>;
 
public:
 
  using reference = Facade::reference;
 
  reference operator*() const
  { return [implement dereferencing here]; }
 
  FooIterator& operator++() const
  { [implement incrementing here]; return *this; }
 
  friend bool operator==(const FooIterator& it1, const FooIterator& it2)
  { return [implement comparison here]; }
};

Alternatively the iterator can delegate arithmetic operations and comparisons to an underlying iterator/pointer/number (option 2 above). E.g. a random access iterator where the iterator position is identified by a consecutive number can be implemented as:

class BarIterator
  : public Dune::IteratorFacade<BarIterator, std::random_access_iterator_tag, V>
{
  using Facade = Dune::IteratorFacade<BarIterator, std::random_access_iterator_tag, V>;
 
public:
 
  using reference = Facade::reference;
  using difference_type = Facade::difference_type;
 
  // Only implement dereferencing manually
  reference operator*() const
  { return [implement dereferencing at current position p_ here]; }
 
private:
 
  // Delegate arithmetic operations and comparisons to p_ by exporting
  // it in const and mutable form using baseIterator().
  difference_type& baseIterator() { return p_; }
  const difference_type& baseIterator() const { return p_; }
 
  // Grant access to the private baseIterator() by a friend declaration.
  friend Dune::IteratorFacadeAccess;
 
  difference_type p_;
};

When providing baseIterator() individual method can still be overloaded by implementing them manually. E.g. a random access iterator for values of type V that returns reference-like proxy objects of type R instead of plain V& references and relies on an underlying iterator except for equality comparison can be implemented as:

class ProxyIterator
  : public Dune::IteratorFacade<ProxyIterator, std::random_access_iterator_tag, V, R, Dune::ProxyArrowResult<R>>
{
  using Facade = Dune::IteratorFacade<ProxyIterator, std::random_access_iterator_tag, V, R, Dune::ProxyArrowResult<R>>;
 
public:
 
  using reference = Facade::reference;
 
  // Dereferencing yields copies of type R=reference
  reference operator*() const
  { return [implement dereferencing at current position it_ here]; }
 
  // Override comparison manually here
  friend bool operator==(const ProxyIterator& it1, const ProxyIterator& it2)
  { return [implement custom comparison here]; }
 
private:
 
  // Delegate arithmetic operations to underlying base iterator.
  BaseIterator& baseIterator() { return it_; }
  const BaseIterator& baseIterator() const { return it_; }
  friend Dune::IteratorFacadeAccess;
 
  BaseIterator it_;
};

Template Parameters

It	The derived iterator class
C	Tag class of iterator category
V	The value type
R	The reference type, defaults to V&
P	Pointer type, defaults to V*
D	The type for differences between two iterators, defaults to std::ptrdiff_t

Member Function Documentation

operator+()

template<class It , class C , class V , class R = V&, class P = V*, class D = std::ptrdiff_t>

template<bool dummy = true, std::enable_if_t< isRandomAccess and dummy, int > = 0>

constexpr DerivedIterator Dune::IteratorFacade< It, C, V, R, P, D >::operator+ ( difference_type  n ) const

inlineconstexpr

Create iterator incremented by given value.

Only enabled for random-access iterators.

References Dune::IteratorFacade< It, C, V, R, P, D >::derived().

operator+=()

template<class It , class C , class V , class R = V&, class P = V*, class D = std::ptrdiff_t>

template<bool dummy = true, std::enable_if_t< isRandomAccess and dummy, int > = 0>

constexpr decltype(auto) Dune::IteratorFacade< It, C, V, R, P, D >::operator+= ( difference_type  n )

inlineconstexpr

Increment iterator by given value.

Only enabled for random-access iterators.

References Dune::IteratorFacade< It, C, V, R, P, D >::derived().

operator-()

template<class It , class C , class V , class R = V&, class P = V*, class D = std::ptrdiff_t>

template<bool dummy = true, std::enable_if_t< isRandomAccess and dummy, int > = 0>

constexpr DerivedIterator Dune::IteratorFacade< It, C, V, R, P, D >::operator- ( difference_type  n ) const

inlineconstexpr

Create iterator decremented by given value.

Only enabled for random-access iterators.

References Dune::IteratorFacade< It, C, V, R, P, D >::derived().

operator--() [1/2]

template<class It , class C , class V , class R = V&, class P = V*, class D = std::ptrdiff_t>

template<bool dummy = true, std::enable_if_t< isBidirectional and dummy, int > = 0>

constexpr decltype(auto) Dune::IteratorFacade< It, C, V, R, P, D >::operator-- ( )

inlineconstexpr

Predecrement operator.

Only enabled for bidirectional and random-access iterators.

References Dune::IteratorFacade< It, C, V, R, P, D >::derived().

Referenced by Dune::IteratorFacade< It, C, V, R, P, D >::operator--().

operator--() [2/2]

template<class It , class C , class V , class R = V&, class P = V*, class D = std::ptrdiff_t>

template<bool dummy = true, std::enable_if_t< isBidirectional and dummy, int > = 0>

constexpr DerivedIterator Dune::IteratorFacade< It, C, V, R, P, D >::operator-- ( int  )

inlineconstexpr

Postdecrement operator.

Only enabled for bidirectional and random-access iterators.

References Dune::IteratorFacade< It, C, V, R, P, D >::derived(), and Dune::IteratorFacade< It, C, V, R, P, D >::operator--().

operator-=()

template<class It , class C , class V , class R = V&, class P = V*, class D = std::ptrdiff_t>

template<bool dummy = true, std::enable_if_t< isRandomAccess and dummy, int > = 0>

constexpr DerivedIterator & Dune::IteratorFacade< It, C, V, R, P, D >::operator-= ( difference_type  n )

inlineconstexpr

Decrement iterator by given value.

Only enabled for random-access iterators.

References Dune::IteratorFacade< It, C, V, R, P, D >::derived().

operator[]()

template<class It , class C , class V , class R = V&, class P = V*, class D = std::ptrdiff_t>

template<bool dummy = true, std::enable_if_t< isRandomAccess and dummy, int > = 0>

constexpr reference Dune::IteratorFacade< It, C, V, R, P, D >::operator[] ( difference_type  n ) const

inlineconstexpr

Dereference element with given offset form this iterator.

Parameters

n	The distance to the element.

Returns

The element at that distance.

Only enabled for random-access iterators.

References Dune::IteratorFacade< It, C, V, R, P, D >::derived().

---

The documentation for this class was generated from the following file:

• dune/common/iteratorfacades.hh