DUNE PDELab (git)

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 DerivedIteratoroperator-= (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 DerivedIteratorderived () const
 Cast of *this to const DerivedIterator type.
 
constexpr DerivedIteratorderived ()
 Cast of *this to DerivedIterator type.
 

Friends

template<bool dummy = true, std::enable_if_t< isRandomAccess and dummy, int > = 0>
constexpr DerivedIterator operator+ (difference_type n, const IteratorFacade &it)
 Create iterator incremented by given value. More...
 

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>
{
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]; }
};
CRTP-Mixing class for stl conformant iterators of given iterator category.
Definition: iteratorfacades.hh:1053
constexpr decltype(auto) operator*() const
Dereferencing operator.
Definition: iteratorfacades.hh:1119
constexpr decltype(auto) operator++()
Preincrement operator.
Definition: iteratorfacades.hh:1138
EnableIfInterOperable< T1, T2, bool >::type operator==(const ForwardIteratorFacade< T1, V1, R1, D > &lhs, const ForwardIteratorFacade< T2, V2, R2, D > &rhs)
Checks for equality.
Definition: iteratorfacades.hh:238

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>
{
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.
difference_type p_;
};
This class encapsulates access of IteratorFacade.
Definition: iteratorfacades.hh:786

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>>
{
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_; }
BaseIterator it_;
};
Template Parameters
ItThe derived iterator class
CTag class of iterator category
VThe value type
RThe reference type, defaults to V&
PPointer type, defaults to V*
DThe 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
nThe 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().

Friends And Related 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 operator+ ( difference_type  n,
const IteratorFacade< It, C, V, R, P, D > &  it 
)
friend

Create iterator incremented by given value.

Only enabled for random-access iterators.


The documentation for this class was generated from the following file:
Creative Commons License   |  Legal Statements / Impressum  |  Hosted by TU Dresden  |  generated with Hugo v0.111.3 (Nov 23, 23:29, 2024)