IteratorRange< Iterator > Class Template Reference

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

Public Types
using	IteratorOverIterators = ::IteratorOverIterators< Iterator >
using	iterator = Iterator

Public Member Functions
	IteratorRange ()
	IteratorRange (const iterator begin, const iterator end)
IteratorOverIterators	begin ()
IteratorOverIterators	begin () const
IteratorOverIterators	end () const
IteratorOverIterators	end ()

Private Attributes
const IteratorOverIterators	it_begin
const IteratorOverIterators	it_end

Detailed Description

template<typename Iterator>
class IteratorRange< Iterator >

A class that is used to denote a collection of iterators that can be expressed in terms of a range of iterators characterized by a begin and an end iterator. As is common in C++, these ranges are specified as half open intervals defined by a begin iterator and a one-past-the-end iterator.

The purpose of this class is so that classes such as Triangulation and DoFHandler can return ranges of cell iterators using an object of the current type from functions such as Triangulation::cell_iterators() and that such an object can then be used in a range-based for loop as supported by C++11, see also C++11 standard.

For example, such a loop could look like this if the goal is to set the user flag on every active cell:

Triangulation<dim> triangulation;
...
for (auto &cell : triangulation.active_cell_iterators())
  cell->set_user_flag();

In other words, the cell objects are iterators, and the range object returned by Triangulation::active_cell_iterators() and similar functions are conceptually thought of as collections of iterators.

Of course, the class may also be used to denote other iterator ranges using different kinds of iterators into other containers.

Class design: Motivation

Informally, the way the C++11 standard describes range- based for loops works as follows: A range-based for loop of the form

Container c;
for (auto v : c)
  statement;

where c is a container or collection, is equivalent to the following loop:

Container c;
for (auto tmp=c.begin(); tmp!=c.end(); ++tmp)
  {
    auto v = *tmp;
    statement;
  }

(The precise definition can be found here: https://en.cppreference.com/w/cpp/language/range-for .) In other words, the compiler introduces a temporary variable that iterates over the elements of the container or collection, and the original variable v that appeared in the range-based for loop represents the dereferenced state of these iterators – namely, the elements of the collection.

In the context of loops over cells, we typically want to retain the fact that the loop variable is an iterator, not a value. This is because in deal.II, we never actually use the dereferenced state of a cell iterator: conceptually, it would represent a cell, and technically it is implemented by classes such as CellAccessor and DoFCellAccessor, but these classes are never used explicitly. Consequently, what we would like is that a call such as Triangulation::active_cell_iterators() returns an object that represents a collection of iterators of the kind {begin, begin+1, ..., end-1}. This is conveniently expressed as the half open interval [begin,end). The loop variable in the range- based for loop would then take on each of these iterators in turn.

Class design: Implementation

To represent the desired semantics as outlined above, this class stores a half-open range of iterators [b,e) of the given template type. Secondly, the class needs to provide begin() and end() functions in such a way that if you dereference the result of IteratorRange::begin(), you get the b iterator. Furthermore, you must be able to increment the object returned by IteratorRange::begin() so that *(++begin()) == b+1. In other words, IteratorRange::begin() must return an iterator that when dereferenced returns an iterator of the template type Iterator: It is an iterator over iterators in the same sense as if you had a pointer into an array of pointers.

This is implemented in the form of the IteratorRange::IteratorOverIterators class.

Definition at line 128 of file iterator_range.h.

Member Typedef Documentation

IteratorOverIterators

template<typename Iterator >

using IteratorRange< Iterator >::IteratorOverIterators = ::IteratorOverIterators<Iterator>

Typedef for the iterator type that iterates over other iterators.

Definition at line 134 of file iterator_range.h.

iterator

template<typename Iterator >

using IteratorRange< Iterator >::iterator = Iterator

Typedef for the iterator type represent by this class.

Definition at line 140 of file iterator_range.h.

Constructor & Destructor Documentation

IteratorRange() [1/2]

template<typename Iterator >

IteratorRange< Iterator >::IteratorRange

inline

Default constructor. Create a range represented by two default constructed iterators. This range is likely (depending on the type of the iterators) empty.

Definition at line 370 of file iterator_range.h.

IteratorRange() [2/2]

template<typename Iterator >

IteratorRange< Iterator >::IteratorRange ( const iterator  begin, const iterator  end  )

inline

Constructor. Constructs a range given the begin and end iterators.

Parameters

[in]	begin	An iterator pointing to the first element of the range
[in]	end	An iterator pointing past the last element represented by this range.

Definition at line 378 of file iterator_range.h.

Member Function Documentation

begin() [1/2]

template<typename Iterator >

IteratorRange< Iterator >::IteratorOverIterators IteratorRange< Iterator >::begin

inline

Return the iterator pointing to the first element of this range.

Definition at line 387 of file iterator_range.h.

begin() [2/2]

template<typename Iterator >

IteratorRange< Iterator >::IteratorOverIterators IteratorRange< Iterator >::begin

inline

Return the iterator pointing to the first element of this range.

Definition at line 395 of file iterator_range.h.

end() [1/2]

template<typename Iterator >

IteratorRange< Iterator >::IteratorOverIterators IteratorRange< Iterator >::end

inline

Return the iterator pointing to the element past the last element of this range.

Definition at line 411 of file iterator_range.h.

end() [2/2]

template<typename Iterator >

IteratorRange< Iterator >::IteratorOverIterators IteratorRange< Iterator >::end

inline

Return the iterator pointing to the element past the last element of this range.

Definition at line 403 of file iterator_range.h.

Member Data Documentation

it_begin

template<typename Iterator >

const IteratorOverIterators IteratorRange< Iterator >::it_begin

private

Iterators characterizing the begin and end of the range.

Definition at line 188 of file iterator_range.h.

it_end

template<typename Iterator >

const IteratorOverIterators IteratorRange< Iterator >::it_end

private

Definition at line 189 of file iterator_range.h.

---

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

• include/deal.II/base/iterator_range.h