[ VIGRA Homepage | Function Index | Class Index | Namespaces | File List | Main Page ]
General iterators for arrays of arbitrary dimension.
The Multidimensional Iterator concept allows navigation on arrays of arbitrary dimension. It provides two modes of iteration: direct traversal, and hierarchical traversal. In general, hierarchical traversal will be faster, while only direct traversal allows for true random access in all dimensions. Via the dim<K>()
function, operations applying to a particular dimension can be used in the direct traversal mode. In contrast, direct traversal functions should not be used in the hierarchical mode because the hierarchical functions are only well-defined if the iterator points to element 0 in all dimensions below its current dimension. The current dimension of a MultiIterator<N, ...>
is N-1
.
Local Types | Meaning | |
---|---|---|
MultiIterator::value_type | the underlying arrays's pixel type | |
MultiIterator::reference | the iterator's reference type (return type of *iter ). Will be value_type & for a mutable iterator, and convertible to value_type const & for a const iterator. | |
MultiIterator::pointer | the iterator's pointer type (return type of iter.operator->() ). Will be value_type * for a mutable iterator, and convertible to value_type const * for a const iterator. | |
MultiIterator::iterator_category | the iterator tag (vigra::multi_dimensional_traverser_tag ) | |
Operation | Result | Semantics |
MultiIterator k; | default constructor | |
MultiIterator k(i); | copy constructor | |
k = i | MultiIterator & | assignment |
i == j | bool | equality (iterators point to the same element) |
i != j | bool | inequality (iterators don't point to the same element) |
*i | MultiIterator::reference | access the current element |
i->member() | depends on operation | call member function of underlying pixel type via operator-> of iterator |
Local Types | Meaning | |
---|---|---|
MultiIterator::multi_difference_type | the iterator's multi-dimensional difference type (TinyVector<MultiArrayIndex, N> ) | |
Operation | Result | Semantics |
i += diff | MultiIterator & | add offset to current position |
i -= diff | MultiIterator & | subtract offset from current position |
i + diff | MultiIterator | create traverser by adding offset |
i - diff | MultiIterator | create traverser by subtracting offset |
i[diff] | MultiIterator::reference | access element at offset diff |
i.dim<K>() | MultiIterator<K+1, T, ...> | Access the traverser with the current dimension set to K. Typically used to call navigation functions referring to a particular dimension. Example (assuming i, j are 3-dimensional):i.dim<0>()++; // increment dimension 0
i.dim<1>()++; // increment dimension 1
i.dim<2>()++; // increment dimension 2
j += MultiIterator::multi_difference_type(1,1,1); // same effect
MultiArrayShape< N >::type multi_difference_type Definition multi_iterator.hxx:1188 |
i, j are of type MultiIterator diff is of type MultiIterator::multi_difference_type K is an integer compile-time constant |
Note that it is impossible to support an operator-
between two iterators which returns a MultiIterator::multi_difference_type
because it is impossible to decide to which dimension a difference applies. Consider for example, a 2-dimensional iterator i
, and let j = i + multi_difference_type(width, 0)
, k = i + multi_difference_type(0,1)
, where width
is the array's total width. In general, j
and k
point to the same memory location, so that the two cases cannot easily be distinguished (it is possible, but iterator performance will suffer significantly, as is experienced with ImageIterator where differencing is allowed).
Local Types | Meaning | |
---|---|---|
MultiIterator::difference_type | the iterator's difference type (MultiArrayIndex ) | |
MultiIterator::next_type | type of the next iterator (referring to the next lower dimension) in the hierarchy | |
Operation | Result | Semantics |
++i | MultiIterator & | pre-increment iterator in its current dimension |
i++ | MultiIterator | post-increment iterator in its current dimension |
–i | MultiIterator & | pre-decrement iterator in its current dimension |
i– | MultiIterator | post-decrement iterator in its current dimension |
i += d | MultiIterator & | add d in current dimension |
i -= d | MultiIterator & | subtract d in from dimension |
i + d | MultiIterator | create new iterator by adding d in current dimension |
i - d | MultiIterator | create new iterator by subtracting d in current dimension |
i - j | difference_type | difference of i and j in the current dimensionNote: The result of this operation is undefined if the iterator doesn't point to element 0 in all dimensions below its current dimension. |
i < j | bool | i - j < 0 Note: The result of this operation is undefined if the iterator doesn't point to element 0 in all dimensions below its current dimension. |
i[d] | MultiIterator::reference | access element by adding offset d in current dimension |
i.begin() | next_type | create the hierarchical iterator pointing to the first element in the next lower dimension. Note: The result of this operation is undefined if the iterator doesn't point to element 0 in all dimensions below its current dimension. Usage: MultiIterator<3, int> i3 = ..., end3 = ...;
for(; i3 != end3; ++i3)
{
for(; i2 != end2; ++i2)
{
for(; i1 != end1; ++i1)
{
... // do something with the current element
}
}
}
|
i.end() | next_type | create the hierarchical iterator pointing to the past-the-end location in the next lower dimension. Note: The result of this operation is undefined if the iterator doesn't point to element 0 in all dimensions below its current dimension. |
i, j are of type MultiIterator d is of type MultiIterator::difference_type |
© Ullrich Köthe (ullrich.koethe@iwr.uni-heidelberg.de) |
html generated using doxygen and Python
|