#include <deal.II/base/linear_index_iterator.h>

Inheritance diagram for LinearIndexIterator< DerivedIterator, AccessorType >:

[legend]

Public Types
using	iterator_category = std::random_access_iterator_tag

using	value_type = AccessorType

using	difference_type = std::ptrdiff_t

using	reference = const value_type &

using	pointer = const value_type *

using	size_type = typename value_type::size_type

Public Member Functions
DerivedIterator &	operator= (const DerivedIterator &it)

DerivedIterator &	operator++ ()

DerivedIterator	operator++ (int)

DerivedIterator &	operator-- ()

DerivedIterator	operator-- (int)

DerivedIterator	operator+ (const difference_type n) const

DerivedIterator	operator- (const difference_type n) const

DerivedIterator &	operator+= (const difference_type n)

DerivedIterator &	operator-= (const difference_type n)

difference_type	operator- (const DerivedIterator &p) const

reference	operator* () const

pointer	operator-> () const

template<typename OtherIterator >
std::enable_if_t< std::is_convertible_v< OtherIterator, DerivedIterator >, bool >	operator== (const OtherIterator &right) const

template<typename OtherIterator >
std::enable_if_t< std::is_convertible_v< OtherIterator, DerivedIterator >, bool >	operator!= (const OtherIterator &right) const

bool	operator<= (const DerivedIterator &) const

bool	operator>= (const DerivedIterator &) const

bool	operator< (const DerivedIterator &) const

bool	operator> (const DerivedIterator &) const

Protected Member Functions
	LinearIndexIterator ()=default

	LinearIndexIterator (const AccessorType accessor)

Protected Attributes
AccessorType	accessor

Detailed Description

template<typename DerivedIterator, typename AccessorType>
class LinearIndexIterator< DerivedIterator, AccessorType >

Many classes in deal.II, such as FullMatrix, TransposeTable, and SparseMatrix, store their data in contiguous buffers (though the interpretation of what the elements of these buffers represent can, of course, be complex). For example, FullMatrix and TransposeTable store their data in row major and column major order respectively, whereas for SparseMatrix the mapping from buffer location to matrix entry \(\mathbf{A}(i, j)\) is more complicated. In any case, however, the contiguous arrangements of elements enables random access iteration.

LinearIndexIterator provides most of the functionality needed to write iterators for these classes. LinearIndexIterator is essentially a simplified version of boost::iterator_facade that assumes AccessorType provides certain members (documented below) that completely describe the state of the iterator. The intended use of this class is for containers to define their own accessor classes and then use the curiously recurring template pattern (CRTP) technique to define their iterators. For example, here is a container that uses LinearIndexIterator to define its own iterator classes:

template <typename T>
class Container
{
protected:
  // forward declaration for friendship
  template <bool Constness>
  class Iterator;
 
  template <bool Constness>
  class Accessor
  {
  public:
    // const iterators store a const pointer
    using container_pointer_type
      = std::conditional_t<Constness,
                           const Container<T>*,
                           Container<T>*>;
 
    // This alias is assumed to exist.
    using size_type = std::size_t;
 
    // constructor.
    Accessor(const container_pointer_type container,
             const std::ptrdiff_t index);
 
    // constructor.
    Accessor();
 
    // get a constant reference to the current value.
    const T& value() const;
 
  protected:
    container_pointer_type container;
    std::ptrdiff_t linear_index;
 
    // LinearIndexIterator needs access to linear_index and container.
    friend class LinearIndexIterator<Iterator<Constness>,
                                     Accessor<Constness>>;
  };
 
  template <bool Constness>
  class Iterator : public LinearIndexIterator<Iterator<Constness>,
                                              Accessor<Constness>>
  {
    // Constructor.
    Iterator(Container<T> * const container, const std::ptrdiff_t index);
 
    // implement additional constructors here, but all state should be
    // contained in the Accessor, which is a member of the base class.
  };
 
public:
  using size_type = std::size_t;
  using const_iterator = Iterator<true>;
  using iterator = Iterator<false>;
 
  iterator begin ();
  iterator end ();
 
  const_iterator begin () const;
  const_iterator end () const;
};

Template Parameters

DerivedIterator As shown in the example above, concrete iterator classes should use this class with the CRTP technique: this provides the boiler-plate comparison and arithmetic operators for iterators. This is necessary for, e.g., LinearIndexIterator::operator++() to return the correct type.

AccessorType

LinearIndexIterator assumes that the AccessorType template parameter has the following members which completely describe the current state of the iterator:

A pointer named container to the original container (e.g., the relevant SparseMatrix). This should be a const pointer for const iterators.
An array index named linear_index that stores the current position in the container's storage buffer. linear_index does not need to be an integer: it could be a class type (convertible to the correct index type of the container) that implements operator+=, operator<, and operator==. For example, one could implement a strided iterator by implementing operator+= and operator- with multiplicative factors.

In addition, AccessorType should declare the relevant LinearIndexIterator instantiation to be a friend and define a size_type type.

Note: TransposeTable uses this template to implement its iterators.

Definition at line 138 of file linear_index_iterator.h.

Member Typedef Documentation

◆ iterator_category

template<typename DerivedIterator , typename AccessorType >

using LinearIndexIterator< DerivedIterator, AccessorType >::iterator_category = std::random_access_iterator_tag

Iterator category.

Definition at line 147 of file linear_index_iterator.h.

◆ value_type

template<typename DerivedIterator , typename AccessorType >

using LinearIndexIterator< DerivedIterator, AccessorType >::value_type = AccessorType

An alias for the type you get when you dereference an iterator of the current kind.

Definition at line 154 of file linear_index_iterator.h.

◆ difference_type

template<typename DerivedIterator , typename AccessorType >

using LinearIndexIterator< DerivedIterator, AccessorType >::difference_type = std::ptrdiff_t

Difference type.

Definition at line 159 of file linear_index_iterator.h.

◆ reference

template<typename DerivedIterator , typename AccessorType >

using LinearIndexIterator< DerivedIterator, AccessorType >::reference = const value_type &

Reference type.

Definition at line 164 of file linear_index_iterator.h.

◆ pointer

template<typename DerivedIterator , typename AccessorType >

using LinearIndexIterator< DerivedIterator, AccessorType >::pointer = const value_type *

Pointer type.

Definition at line 169 of file linear_index_iterator.h.

◆ size_type

template<typename DerivedIterator , typename AccessorType >

using LinearIndexIterator< DerivedIterator, AccessorType >::size_type = typename value_type::size_type

Size type used by the underlying container.

Definition at line 174 of file linear_index_iterator.h.

Constructor & Destructor Documentation

◆ LinearIndexIterator() [1/2]

template<typename DerivedIterator , typename AccessorType >

LinearIndexIterator< DerivedIterator, AccessorType >::LinearIndexIterator ( )

protecteddefault

◆ LinearIndexIterator() [2/2]

template<typename DerivedIterator , typename AccessorType >

LinearIndexIterator< DerivedIterator, AccessorType >::LinearIndexIterator ( const AccessorType accessor )

inlineprotected

Constructor that copies an accessor.

Definition at line 503 of file linear_index_iterator.h.

Member Function Documentation

◆ operator=()

template<typename DerivedIterator , typename AccessorType >

DerivedIterator & LinearIndexIterator< DerivedIterator, AccessorType >::operator= ( const DerivedIterator & it )

inline

Copy operator.

Definition at line 332 of file linear_index_iterator.h.

◆ operator++() [1/2]

template<typename DerivedIterator , typename AccessorType >

DerivedIterator & LinearIndexIterator< DerivedIterator, AccessorType >::operator++ ( )

inline

Prefix increment.

Definition at line 344 of file linear_index_iterator.h.

◆ operator++() [2/2]

template<typename DerivedIterator , typename AccessorType >

DerivedIterator LinearIndexIterator< DerivedIterator, AccessorType >::operator++ ( int )

inline

Postfix increment.

Definition at line 353 of file linear_index_iterator.h.

◆ operator--() [1/2]

template<typename DerivedIterator , typename AccessorType >

DerivedIterator & LinearIndexIterator< DerivedIterator, AccessorType >::operator-- ( )

inline

Prefix decrement.

Definition at line 364 of file linear_index_iterator.h.

◆ operator--() [2/2]

template<typename DerivedIterator , typename AccessorType >

DerivedIterator LinearIndexIterator< DerivedIterator, AccessorType >::operator-- ( int )

inline

Postfix decrement.

Definition at line 373 of file linear_index_iterator.h.

◆ operator+()

template<typename DerivedIterator , typename AccessorType >

DerivedIterator LinearIndexIterator< DerivedIterator, AccessorType >::operator+ ( const difference_type n ) const

inline

Return an iterator that is n entries ahead of the current one.

Definition at line 384 of file linear_index_iterator.h.

◆ operator-() [1/2]

template<typename DerivedIterator , typename AccessorType >

DerivedIterator LinearIndexIterator< DerivedIterator, AccessorType >::operator- ( const difference_type n ) const

inline

Return an iterator that is n entries behind the current one.

Definition at line 396 of file linear_index_iterator.h.

◆ operator+=()

template<typename DerivedIterator , typename AccessorType >

DerivedIterator & LinearIndexIterator< DerivedIterator, AccessorType >::operator+= ( const difference_type n )

inline

Increment the iterator position by n.

Definition at line 408 of file linear_index_iterator.h.

◆ operator-=()

template<typename DerivedIterator , typename AccessorType >

DerivedIterator & LinearIndexIterator< DerivedIterator, AccessorType >::operator-= ( const difference_type n )

inline

Decrement the iterator position by n.

Definition at line 419 of file linear_index_iterator.h.

◆ operator-() [2/2]

template<typename DerivedIterator , typename AccessorType >

LinearIndexIterator< DerivedIterator, AccessorType >::difference_type LinearIndexIterator< DerivedIterator, AccessorType >::operator- ( const DerivedIterator & p ) const

inline

Return the distance between the current iterator and the argument. The distance is given by how many times one has to apply operator++() to the current iterator to get the argument (for a positive return value), or operator--() (for a negative return value).

Definition at line 430 of file linear_index_iterator.h.

◆ operator*()

template<typename DerivedIterator , typename AccessorType >

LinearIndexIterator< DerivedIterator, AccessorType >::reference LinearIndexIterator< DerivedIterator, AccessorType >::operator* ( ) const

inline

Dereferencing operator.

Definition at line 443 of file linear_index_iterator.h.

◆ operator->()

template<typename DerivedIterator , typename AccessorType >

LinearIndexIterator< DerivedIterator, AccessorType >::pointer LinearIndexIterator< DerivedIterator, AccessorType >::operator-> ( ) const

inline

Dereferencing operator.

Definition at line 452 of file linear_index_iterator.h.

◆ operator==()

template<typename DerivedIterator , typename AccessorType >

template<typename OtherIterator >

std::enable_if_t< std::is_convertible_v< OtherIterator, DerivedIterator >, bool > LinearIndexIterator< DerivedIterator, AccessorType >::operator== ( const OtherIterator & right ) const

inline

Comparison operator. Returns true if both iterators point to the same entry in the same container.

Definition at line 257 of file linear_index_iterator.h.

◆ operator!=()

template<typename DerivedIterator , typename AccessorType >

template<typename OtherIterator >

std::enable_if_t< std::is_convertible_v< OtherIterator, DerivedIterator >, bool > LinearIndexIterator< DerivedIterator, AccessorType >::operator!= ( const OtherIterator & right ) const

inline

Opposite of operator==().

Definition at line 268 of file linear_index_iterator.h.

◆ operator<=()

template<typename DerivedIterator , typename AccessorType >

bool LinearIndexIterator< DerivedIterator, AccessorType >::operator<= ( const DerivedIterator & other ) const

inline

Comparison operator: uses the same ordering as operator<(), but also checks for equality.

This function is only valid if both iterators point into the same container.

Definition at line 460 of file linear_index_iterator.h.

◆ operator>=()

template<typename DerivedIterator , typename AccessorType >

bool LinearIndexIterator< DerivedIterator, AccessorType >::operator>= ( const DerivedIterator & other ) const

inline

Comparison operator: uses the same ordering as operator>(), but also checks for equality.

This function is only valid if both iterators point into the same container.

Definition at line 471 of file linear_index_iterator.h.

◆ operator<()

template<typename DerivedIterator , typename AccessorType >

bool LinearIndexIterator< DerivedIterator, AccessorType >::operator< ( const DerivedIterator & other ) const

inline

Comparison operator. Result is true if either the first row number is smaller or if the row numbers are equal and the first index is smaller.

This function is only valid if both iterators point into the same container.

Definition at line 480 of file linear_index_iterator.h.

◆ operator>()

template<typename DerivedIterator , typename AccessorType >

bool LinearIndexIterator< DerivedIterator, AccessorType >::operator> ( const DerivedIterator & other ) const

inline

Comparison operator. Works in the same way as operator<(), just the other way round.

Definition at line 494 of file linear_index_iterator.h.

Member Data Documentation

◆ accessor

template<typename DerivedIterator , typename AccessorType >

AccessorType LinearIndexIterator< DerivedIterator, AccessorType >::accessor

protected

Store an object of the accessor class.

Definition at line 325 of file linear_index_iterator.h.

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

include/deal.II/base/linear_index_iterator.h

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ iterator_category

◆ value_type

◆ difference_type

◆ reference

◆ pointer

◆ size_type

Constructor & Destructor Documentation

◆ LinearIndexIterator() [1/2]

◆ LinearIndexIterator() [2/2]

Member Function Documentation

◆ operator=()

◆ operator++() [1/2]

◆ operator++() [2/2]

◆ operator--() [1/2]

◆ operator--() [2/2]

◆ operator+()

◆ operator-() [1/2]

◆ operator+=()

◆ operator-=()

◆ operator-() [2/2]

◆ operator*()

◆ operator->()

◆ operator==()

◆ operator!=()

◆ operator<=()

◆ operator>=()

◆ operator<()

◆ operator>()

Member Data Documentation

◆ accessor