Reference documentation for deal.II version Git 8a2af55 2018-04-22 07:16:45 +0200
Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
LinearIndexIterator< DerivedIterator, AccessorType > Class Template Reference

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

Inheritance diagram for LinearIndexIterator< DerivedIterator, AccessorType >:
[legend]

Public Types

typedef std::random_access_iterator_tag iterator_category
 
typedef AccessorType value_type
 
typedef std::ptrdiff_t difference_type
 
typedef const value_typereference
 
typedef const value_typepointer
 
typedef value_type::size_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
 
bool operator== (const DerivedIterator &) const
 
bool operator!= (const DerivedIterator &) 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<class DerivedIterator, class 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
typedef typename std::conditional<Constness, const Container<T>*, Container<T>*>::type
container_pointer_type;
// This typedef is assumed to exist.
typedef std::size_t size_type;
// 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:
typedef std::size_t size_type;
typedef Iterator<true> const_iterator;
typedef Iterator<false> iterator;
iterator begin ();
iterator end ();
const_iterator begin () const;
const_iterator end () const;
};
Template Parameters
DerivedIteratorAs 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.
AccessorTypeLinearIndexIterator assumes that the AccessorType template parameter has the following members which completely describe the current state of the iterator:
  1. A pointer named container to the original container (e.g., the relevant SparseMatrix). This should be a const pointer for const iterators.
  2. 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.
Author
David Wells, 2018

Definition at line 135 of file linear_index_iterator.h.

Member Typedef Documentation

template<class DerivedIterator, class AccessorType>
typedef std::random_access_iterator_tag LinearIndexIterator< DerivedIterator, AccessorType >::iterator_category

Iterator category.

Definition at line 141 of file linear_index_iterator.h.

template<class DerivedIterator, class AccessorType>
typedef AccessorType LinearIndexIterator< DerivedIterator, AccessorType >::value_type

A typedef for the type you get when you dereference an iterator of the current kind.

Definition at line 148 of file linear_index_iterator.h.

template<class DerivedIterator, class AccessorType>
typedef std::ptrdiff_t LinearIndexIterator< DerivedIterator, AccessorType >::difference_type

Difference type.

Definition at line 153 of file linear_index_iterator.h.

template<class DerivedIterator, class AccessorType>
typedef const value_type& LinearIndexIterator< DerivedIterator, AccessorType >::reference

Reference type.

Definition at line 158 of file linear_index_iterator.h.

template<class DerivedIterator, class AccessorType>
typedef const value_type* LinearIndexIterator< DerivedIterator, AccessorType >::pointer

Pointer type.

Definition at line 163 of file linear_index_iterator.h.

template<class DerivedIterator, class AccessorType>
typedef value_type::size_type LinearIndexIterator< DerivedIterator, AccessorType >::size_type

Size type used by the underlying container.

Definition at line 168 of file linear_index_iterator.h.

Constructor & Destructor Documentation

template<class DerivedIterator, class AccessorType>
LinearIndexIterator< DerivedIterator, AccessorType >::LinearIndexIterator ( )
protecteddefault

The inheriting class should have a default constructor.

template<class DerivedIterator , class AccessorType>
LinearIndexIterator< DerivedIterator, AccessorType >::LinearIndexIterator ( const AccessorType  accessor)
inlineprotected

Constructor that copies an accessor.

Definition at line 507 of file linear_index_iterator.h.

Member Function Documentation

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

Copy operator.

Definition at line 301 of file linear_index_iterator.h.

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

Prefix increment.

Definition at line 313 of file linear_index_iterator.h.

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

Postfix increment.

Definition at line 323 of file linear_index_iterator.h.

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

Prefix decrement.

Definition at line 335 of file linear_index_iterator.h.

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

Postfix decrement.

Definition at line 345 of file linear_index_iterator.h.

template<class DerivedIterator , class 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 358 of file linear_index_iterator.h.

template<class DerivedIterator , class 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 371 of file linear_index_iterator.h.

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

Increment the iterator position by n.

Definition at line 383 of file linear_index_iterator.h.

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

Decrement the iterator position by n.

Definition at line 394 of file linear_index_iterator.h.

template<class DerivedIterator, class 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 405 of file linear_index_iterator.h.

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

Dereferencing operator.

Definition at line 417 of file linear_index_iterator.h.

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

Dereferencing operator.

Definition at line 427 of file linear_index_iterator.h.

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

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

Definition at line 438 of file linear_index_iterator.h.

template<class DerivedIterator, class AccessorType >
bool LinearIndexIterator< DerivedIterator, AccessorType >::operator!= ( const DerivedIterator &  other) const
inline

Inverse of operator==().

Definition at line 451 of file linear_index_iterator.h.

template<class DerivedIterator, class 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 462 of file linear_index_iterator.h.

template<class DerivedIterator, class 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 473 of file linear_index_iterator.h.

template<class DerivedIterator, class 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 484 of file linear_index_iterator.h.

template<class DerivedIterator, class 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 497 of file linear_index_iterator.h.

Member Data Documentation

template<class DerivedIterator, class AccessorType>
AccessorType LinearIndexIterator< DerivedIterator, AccessorType >::accessor
protected

Store an object of the accessor class.

Definition at line 293 of file linear_index_iterator.h.


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