#include <deal.II/grid/tria_iterator.h>

Inheritance diagram for TriaRawIterator< Accessor >:

[legend]

Public Types
using	AccessorType = Accessor

using	iterator_category = std::bidirectional_iterator_tag

using	value_type = Accessor

using	difference_type = int

using	pointer = Accessor *

using	reference = Accessor &

Public Member Functions
	TriaRawIterator ()

	TriaRawIterator (const TriaRawIterator &)

	TriaRawIterator (const Accessor &a)

template<typename OtherAccessor >
	TriaRawIterator (const OtherAccessor &a)

	TriaRawIterator (const Triangulation< Accessor::dimension, Accessor::space_dimension > parent, const int level, const int index, const typename AccessorType::AccessorData local_data=nullptr)

template<typename OtherAccessor >
	TriaRawIterator (const TriaRawIterator< OtherAccessor > &i)

	TriaRawIterator (const TriaAccessorBase< Accessor::structure_dimension, Accessor::dimension, Accessor::space_dimension > &tria_accessor, const typename Accessor::AccessorData *local_data)

template<typename OtherAccessor >
	TriaRawIterator (const TriaIterator< OtherAccessor > &i)

template<typename OtherAccessor >
	TriaRawIterator (const TriaActiveIterator< OtherAccessor > &i)

TriaRawIterator &	operator= (const TriaRawIterator &)

template<typename OtherAccessor = Accessor>
std::enable_if_t< std::is_convertible_v< OtherAccessor, Accessor >, bool >	operator== (const TriaRawIterator< OtherAccessor > &) const

bool	operator!= (const TriaRawIterator &) const

bool	operator< (const TriaRawIterator &) const

bool	operator> (const TriaRawIterator &) const

IteratorState::IteratorStates	state () const

template<typename StreamType >
void	print (StreamType &out) const

std::size_t	memory_consumption () const

Dereferencing
Accessor	operator* () const

const Accessor *	operator-> () const

Accessor *	operator-> ()

const Accessor &	access_any () const

Advancement of iterators
TriaRawIterator &	operator++ ()

TriaRawIterator	operator++ (int)

TriaRawIterator &	operator-- ()

TriaRawIterator	operator-- (int)

Static Public Member Functions
Exceptions
static ::ExceptionBase &	ExcDereferenceInvalidCell (Accessor arg1)

static ::ExceptionBase &	ExcDereferenceInvalidObject (Accessor arg1)

static ::ExceptionBase &	ExcAdvanceInvalidObject ()

static ::ExceptionBase &	ExcInvalidComparison ()

Protected Attributes
Accessor	accessor

Friends
template<typename SomeAccessor >
class	TriaRawIterator

template<typename SomeAccessor >
class	TriaIterator

template<typename SomeAccessor >
class	TriaActiveIterator

Detailed Description

template<typename Accessor>
class TriaRawIterator< Accessor >

This class implements an iterator, analogous to those used in the standard library. It fulfills the requirements of a bidirectional iterator. See the C++ documentation for further details of iterator specification and usage.

In addition to the standard interface, an iterator of this class provides a -> operator, i.e. you can write statements like

cell->set_refine_flag ();

Iterators are used whenever a loop over all lines, quads, cells etc. is to be performed. These loops can then be coded like this:

cell_iterator cell = tria.begin();
cell_iterator end  = tria.end();
for (; cell!=end; ++cell)
  if (cell->at_boundary())
    cell->set_refine_flag();

Note the usage of ++cell instead of cell++ since this does not involve temporaries and copying. It is recommended to use a fixed value end inside the loop instead of tria.end(), since the creation and copying of these iterators is rather expensive compared to normal pointers.

The objects pointed to are accessors, derived from TriaAccessorBase. Which kind of accessor is determined by the template argument Accessor. These accessors are not so much data structures as they are a collection of functions providing access to the data stored in Triangulation or DoFHandler objects. Using these accessors, the structure of these classes is hidden from the application program.

Which iterator to use when

Attention: Application programs will rarely use TriaRawIterator, but rather one of the derived classes TriaIterator or TriaActiveIterator.

TriaRawIterator objects point to lines, cells, etc in the lists whether they are used or not (in the vectors, also dead objects are stored, since deletion in vectors is expensive and we also do not want to destroy the ordering induced by the numbering in the vectors). Therefore not all raw iterators point to valid objects.
The derived class TriaIterator selects the valid cells, that is, cells used somewhere in the triangulation hierarchy.
TriaActiveIterator objects which only loop over active cells.

Purpose

Iterators are not much slower than operating directly on the data structures, since they perform the loops that you had to handcode yourself anyway. Most iterator and accessor functions are inlined.

The main functionality of iterators, resides in the ++ and -- operators. These move the iterator forward or backward just as if it were a pointer into an array. Here, this operation is not so easy, since it may include skipping some elements and the transition between the triangulation levels. This is completely hidden from the user, though you can still create an iterator pointing to an arbitrary element. Actually, the operation of moving iterators back and forth is not done in the iterator classes, but rather in the accessor classes. Since these are passed as template arguments, you can write your own versions here to add more functionality.

Furthermore, the iterators described here satisfy the requirement of input and bidirectional iterators as stated by the C++ standard. It is therefore possible to use the functions from the algorithm section of the C++ standard, e.g., count_if (see the documentation for Triangulation for an example) and several others.

Implementation

The iterator class itself does not have much functionality. It only becomes useful when assigned an Accessor (the second template parameter), which really does the access to data. An Accessor has to fulfill some requirements:

It must have two members named present_level and present_index storing the address of the element in the triangulation presently pointed to. These data have to be accessible by all triangulation iterators listed above.
It must have a constructor which takes a Triangulation* and two unsigned integers, denoting the initial level and index, as well as a data object depending on its type.
For the TriaIterator and the TriaActiveIterator class, it must have a member function bool used(), for the latter a member function bool active().
It must have void operators ++ and --.
It must declare a local alias AccessorData which states the data type the accessor expects to get passed as fourth constructor argument. By declaring a local data type, the respective iterator class may type-safely enforce that data type to be one of its own constructor argument types. If an accessor class does not need additional data, this type shall be void.

Then the iterator is able to do what it is supposed to. All of the necessary functions are implemented in the Accessor base class, but you may write your own version (non-virtual, since we use templates) to add functionality.

The accessors provided by the library consist of two groups, determined by whether they access the data of Triangulation objects or DoFHandler objects. They are derived from TriaAccessor and DoFAccessor, respectively. Each group also has specialized accessors for cells (as opposed to faces and lines) that offer more functionality such as accessing neighbors.

Attention: It seems impossible to preserve constness of a triangulation through iterator usage. Thus, if you declare pointers to a const triangulation object, you should be well aware that you might involuntarily alter the data stored in the triangulation.

Note: More information on valid and invalid iterators can be found in the documentation of TriaAccessorBase, where the iterator states are checked and implemented.

Past-the-end iterators

There is a representation of past-the-end-pointers, denoted by special values of the member variables present_level and present_index: If present_level>=0 and present_index>=0, then the object is valid (there is no check whether the triangulation really has that many levels or that many cells on the present level when we investigate the state of an iterator; however, in many places where an iterator is dereferenced we make this check); if present_level==-1 and present_index==-1, then the iterator points past the end; in all other cases, the iterator is considered invalid. You can check this by calling the state() function.

An iterator is also invalid, if the pointer pointing to the Triangulation object is invalid or zero.

Finally, an iterator is invalid, if the element pointed to by present_level and present_index is not used, i.e. if the used flag is set to false.

The last two checks are not made in state() since both cases should only occur upon uninitialized construction through memcpy and the like (the parent triangulation can only be set upon construction). If an iterator is constructed empty through the empty constructor, present_level==-2 and present_index==-2. Thus, the iterator is invalid anyway, regardless of the state of the triangulation pointer and the state of the element pointed to.

Past-the-end iterators may also be used to compare an iterator with the before-the-start value, when running backwards. There is no distinction between the iterators pointing past the two ends of a vector.

By defining only one value to be past-the-end and making all other values invalid provides a second track of security: if we should have forgotten a check in the library when an iterator is incremented or decremented, we automatically convert the iterator from the allowed state "past-the-end" to the disallowed state "invalid" which increases the chance that some time earlier than for past-the-end iterators an exception is raised.

Triangulation

Definition at line 226 of file tria_iterator.h.

Member Typedef Documentation

◆ AccessorType

template<typename Accessor >

using TriaRawIterator< Accessor >::AccessorType = Accessor

Declare the type of the Accessor for use in the outside world. This way other functions can use the Accessor's type without knowledge of how the exact implementation actually is.

Definition at line 234 of file tria_iterator.h.

◆ iterator_category

template<typename Accessor >

using TriaRawIterator< Accessor >::iterator_category = std::bidirectional_iterator_tag

Mark the class as bidirectional iterator and declare some alias which are standard for iterators and are used by algorithms to enquire about the specifics of the iterators they work on.

Definition at line 493 of file tria_iterator.h.

◆ value_type

template<typename Accessor >

using TriaRawIterator< Accessor >::value_type = Accessor

Definition at line 494 of file tria_iterator.h.

◆ difference_type

template<typename Accessor >

using TriaRawIterator< Accessor >::difference_type = int

Definition at line 495 of file tria_iterator.h.

◆ pointer

template<typename Accessor >

using TriaRawIterator< Accessor >::pointer = Accessor *

Definition at line 496 of file tria_iterator.h.

◆ reference

template<typename Accessor >

using TriaRawIterator< Accessor >::reference = Accessor &

Definition at line 497 of file tria_iterator.h.

Constructor & Destructor Documentation

◆ TriaRawIterator() [1/9]

template<typename Accessor >

TriaRawIterator< Accessor >::TriaRawIterator ( )

Default constructor. This constructor creates an iterator pointing to an invalid object. The iterator is consequently not usable.

◆ TriaRawIterator() [2/9]

template<typename Accessor >

TriaRawIterator< Accessor >::TriaRawIterator ( const TriaRawIterator< Accessor > & )

Copy constructor.

◆ TriaRawIterator() [3/9]

template<typename Accessor >

TriaRawIterator< Accessor >::TriaRawIterator ( const Accessor & a )

inlineexplicit

Construct an iterator from the given accessor; the given accessor needs not be of the same type as the accessor of this class is, but it needs to be convertible.

Through this constructor, it is also possible to construct objects for derived iterators:

DoFCellAccessor dof_accessor;

Triangulation::active_cell_iterator cell = dof_accessor;

DoFCellAccessor

Definition dof_accessor.h:1326

TriaActiveIterator

Definition tria_iterator.h:755

Definition at line 948 of file tria_iterator.h.

◆ TriaRawIterator() [4/9]

template<typename Accessor >

template<typename OtherAccessor >

TriaRawIterator< Accessor >::TriaRawIterator ( const OtherAccessor & a )

inlineexplicit

Constructor. Assumes that the other accessor type is convertible to the current one.

Definition at line 956 of file tria_iterator.h.

◆ TriaRawIterator() [5/9]

template<typename Accessor >

TriaRawIterator< Accessor >::TriaRawIterator	(	const Triangulation< Accessor::dimension, Accessor::space_dimension > *	parent,
		const int	level,
		const int	index,
		const typename AccessorType::AccessorData *	local_data = `nullptr`
	)

Proper constructor, initialized with the triangulation, the level and index of the object pointed to. The last parameter is of a type declared by the accessor class.

◆ TriaRawIterator() [6/9]

template<typename Accessor >

template<typename OtherAccessor >

TriaRawIterator< Accessor >::TriaRawIterator ( const TriaRawIterator< OtherAccessor > & i )

inline

This is a conversion operator (constructor) which takes another iterator type and copies the data; this conversion works, if there is a conversion path from the OtherAccessor class to the Accessor class of this object. One such path would be derived class to base class, which for example may be used to get a Triangulation::raw_cell_iterator from a DoFHandler::raw_cell_iterator, since the DoFAccessor class is derived from the TriaAccessorBase class.

Definition at line 964 of file tria_iterator.h.

◆ TriaRawIterator() [7/9]

template<typename Accessor >

TriaRawIterator< Accessor >::TriaRawIterator	(	const TriaAccessorBase< Accessor::structure_dimension, Accessor::dimension, Accessor::space_dimension > &	tria_accessor,
		const typename Accessor::AccessorData *	local_data
	)

Another conversion operator, where we use the pointers to the Triangulation from a TriaAccessorBase object, while the additional data is used according to the actual type of Accessor.

◆ TriaRawIterator() [8/9]

template<typename Accessor >

template<typename OtherAccessor >

TriaRawIterator< Accessor >::TriaRawIterator ( const TriaIterator< OtherAccessor > & i )

inline

Conversion constructor. Same as above with the difference that it converts from TriaIterator classes (not TriaRawIterator).

Definition at line 973 of file tria_iterator.h.

◆ TriaRawIterator() [9/9]

template<typename Accessor >

template<typename OtherAccessor >

TriaRawIterator< Accessor >::TriaRawIterator ( const TriaActiveIterator< OtherAccessor > & i )

inline

Conversion constructor. Same as above with the difference that it converts from TriaActiveIterator classes (not TriaRawIterator).

Definition at line 982 of file tria_iterator.h.

Member Function Documentation

◆ operator*()

template<typename Accessor >

Accessor TriaRawIterator< Accessor >::operator* ( ) const

inline

Dereferencing operator, returns a copy of the underlying accessor for the cell pointed to by the iterator. Usage is thus like (*i).index();

This function has to be specialized explicitly for the different Pointers, to allow an iterator<1,TriangulationLevel<1>::LinesData> to point to tria->lines.cells[index] while for one dimension higher it has to point to tria->quads.cells[index].

You must not dereference invalid or past the end iterators.

Definition at line 991 of file tria_iterator.h.

◆ operator->() [1/2]

template<typename Accessor >

const Accessor * TriaRawIterator< Accessor >::operator-> ( ) const

inline

Dereferencing operator, returns a reference of the internal accessor for the cell pointed to by the iterator. Usage is thus like i->index();

There is a const and a non-const version.

Definition at line 1016 of file tria_iterator.h.

◆ operator->() [2/2]

template<typename Accessor >

Accessor * TriaRawIterator< Accessor >::operator-> ( )

inline

Dereferencing operator, non-const version.

Definition at line 1025 of file tria_iterator.h.

◆ access_any()

template<typename Accessor >

const Accessor & TriaRawIterator< Accessor >::access_any ( ) const

inline

In order be able to assign end-iterators for different accessors to each other, we need an access function which returns the accessor regardless of its state.

Warning: This function should not be used in application programs. It is only intended for limited purposes inside the library and it makes debugging much harder.

Definition at line 1007 of file tria_iterator.h.

◆ operator=()

template<typename Accessor >

TriaRawIterator & TriaRawIterator< Accessor >::operator= ( const TriaRawIterator< Accessor > & )

Assignment operator.

◆ operator==()

template<typename Accessor >

template<typename OtherAccessor = Accessor>

std::enable_if_t< std::is_convertible_v< OtherAccessor, Accessor >, bool > TriaRawIterator< Accessor >::operator== ( const TriaRawIterator< OtherAccessor > & ) const

Compare for equality.

◆ operator!=()

template<typename Accessor >

bool TriaRawIterator< Accessor >::operator!= ( const TriaRawIterator< Accessor > & ) const

Compare for inequality.

◆ operator<()

template<typename Accessor >

bool TriaRawIterator< Accessor >::operator< ( const TriaRawIterator< Accessor > & other ) const

inline

Ordering relation for iterators.

This relation attempts a total ordering of cells.

The relation is defined as follows:

For objects of Accessor::structure_dimension < Accessor::dimension, we simply compare the index of such an object. The ordering is lexicographic according to the following hierarchy (in the sense, that the next test is only applied if the previous was inconclusive):

The past-the-end iterator is always ordered last. Two past-the-end iterators rank the same, thus false is returned in that case.
The level of the cell.
The index of a cell inside the level.

Note: The ordering is not consistent between different processor in a parallel::distributed::Triangulation because we rely on index(), which is likely not the same.

Definition at line 1042 of file tria_iterator.h.

◆ operator>()

template<typename Accessor >

bool TriaRawIterator< Accessor >::operator> ( const TriaRawIterator< Accessor > & other ) const

inline

Another comparison operator, implementing with the same ordering as operator<.

Definition at line 1067 of file tria_iterator.h.

◆ operator++() [1/2]

template<typename Accessor >

TriaRawIterator< Accessor > & TriaRawIterator< Accessor >::operator++ ( )

inline

Prefix ++ operator: ++iterator. This operator advances the iterator to the next element and returns a reference to *this.

Definition at line 1077 of file tria_iterator.h.

◆ operator++() [2/2]

template<typename Accessor >

TriaRawIterator TriaRawIterator< Accessor >::operator++ ( int )

Postfix ++ operator: iterator++. This operator advances the iterator to the next element, but returns an iterator to the element previously pointed to.

Since this operation involves a temporary and a copy operation and since an iterator is quite a large object for a pointer, use the prefix operator ++iterator whenever possible, especially in the header of for loops (for (; iterator!=end; ++iterator)) since there you normally never need the returned value.

◆ operator--() [1/2]

template<typename Accessor >

TriaRawIterator< Accessor > & TriaRawIterator< Accessor >::operator-- ( )

inline

Prefix -- operator: --iterator. This operator moves the iterator to the previous element and returns a reference to *this.

Definition at line 1089 of file tria_iterator.h.

◆ operator--() [2/2]

template<typename Accessor >

TriaRawIterator TriaRawIterator< Accessor >::operator-- ( int )

Postfix -- operator: iterator--. This operator moves the iterator to the previous element, but returns an iterator to the element previously pointed to.

The same applies as for the postfix operator++: If possible, avoid it by using the prefix operator form to avoid the use of a temporary variable.

◆ state()

template<typename Accessor >

IteratorState::IteratorStates TriaRawIterator< Accessor >::state ( ) const

inline

Return the state of the iterator.

Definition at line 1034 of file tria_iterator.h.

◆ print()

template<typename Accessor >

template<typename StreamType >

void TriaRawIterator< Accessor >::print ( StreamType & out ) const

inline

Print the iterator to a stream out. The format is level.index.

Definition at line 1102 of file tria_iterator.h.

◆ memory_consumption()

template<typename Accessor >

std::size_t TriaRawIterator< Accessor >::memory_consumption ( ) const

inline

Determine an estimate for the memory consumption (in bytes) of this object.

Definition at line 1114 of file tria_iterator.h.

Friends And Related Symbol Documentation

◆ TriaRawIterator

template<typename Accessor >

template<typename SomeAccessor >

friend class TriaRawIterator

friend

Definition at line 557 of file tria_iterator.h.

◆ TriaIterator

template<typename Accessor >

template<typename SomeAccessor >

friend class TriaIterator

friend

Definition at line 559 of file tria_iterator.h.

◆ TriaActiveIterator

template<typename Accessor >

template<typename SomeAccessor >

friend class TriaActiveIterator

friend

Definition at line 561 of file tria_iterator.h.

Member Data Documentation

◆ accessor

template<typename Accessor >

Accessor TriaRawIterator< Accessor >::accessor

protected

Object holding the real data.

Definition at line 546 of file tria_iterator.h.

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

include/deal.II/grid/tria_iterator.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Attributes

Friends

Detailed Description

Which iterator to use when

Purpose

Implementation

Past-the-end iterators

Member Typedef Documentation

◆ AccessorType

◆ iterator_category

◆ value_type

◆ difference_type

◆ pointer

◆ reference

Constructor & Destructor Documentation

◆ TriaRawIterator() [1/9]

◆ TriaRawIterator() [2/9]

◆ TriaRawIterator() [3/9]

◆ TriaRawIterator() [4/9]

◆ TriaRawIterator() [5/9]

◆ TriaRawIterator() [6/9]

◆ TriaRawIterator() [7/9]

◆ TriaRawIterator() [8/9]

◆ TriaRawIterator() [9/9]

Member Function Documentation

◆ operator*()

◆ operator->() [1/2]

◆ operator->() [2/2]

◆ access_any()

◆ operator=()

◆ operator==()

◆ operator!=()

◆ operator<()

◆ operator>()

◆ operator++() [1/2]

◆ operator++() [2/2]

◆ operator--() [1/2]

◆ operator--() [2/2]

◆ state()

◆ print()

◆ memory_consumption()

Friends And Related Symbol Documentation

◆ TriaRawIterator

◆ TriaIterator

◆ TriaActiveIterator

Member Data Documentation

◆ accessor