ERC CISST - cisst software

---

vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride > Class Template Reference

#include <vctFixedStrideMatrixIterator.h>

Inheritance diagram for vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >:

[legend]Collaboration diagram for vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >:

[legend]List of all members.

---

Detailed Description

template<class _elementType, vct::stride_type _columnStride, vct::size_type _numColumns, vct::stride_type _rowStride>
class vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >

Matrix iterator.

The matrix iterators are parametrized by the type of matrix element, the stride (pointer increment) in row direction and column direction, and the number of matrix columns spanned by the iterator. The iterator traverses the matrix elements in row-first order, with respect to its matrix, and typically possesses the matrix' strides. Note that the iterator does not use the number of rows, and does not keep track of the current row index in the matrix. This was done in order to keep the iterator's memory size as compact as possible. It does, however, keep track of the current column in the matrix, which is required in order to be able to wrap to the next row when the end of the column is reached.

The matrix iterators conform to the STL specification for a Random Access Iterator. This means that one can access all the elements of a matrix sequentially by subscripting or incrementing the iterator. However, in many cases it is faster to access the elements by row-column indices than by the iterator, since the iterator needs to do the bookkeeping of column indices.

The matrix iterators are defined hierarchically, with the vctFixedStrideMatrixConstIterator being immutable, and vctFixedStrideMatrixIterator derived from it and mutable.

Note:

The comparison operator == compares both the pointer and the column index maintained by the iterator. This was the only way we could ensure that the end() method on the matrix classes (vctConstFixedSizeMatrixBase etc.) will evaluate correctly and be comparable with an iterator that's incremented. However, the ordering of iterators relies only on the values of the pointers. Recall that iterator ordering has reachability issues, and see the next note.

There are reachability issues with our iterators system, though they conform with the STL specifications. Generally, STL does not require reachability between any pair of iterators, except iterators that refer to the same container object. In our case, the iterator may span a vector of memory locations in an arbitrary order, depending on the strides of both rows and columns. In other words, if we trace the memory locations pointed by an iterator which is incremented, they may be incremented or decremented depending on the current column index and the strides. This means that we cannot rely on memory order to order the iterators, and furthermore, we cannot assume reachability in the general case. Reachability is guaranteed only for iterators that were obtained from the same matrix object and have the same directionality (forward or reverse). The correctness of operations like ordering iterators depends on reachability. Therefore, use iterator ordering with care, and do not try to mix iterators from different containers into the same expression.

Definition at line 91 of file vctFixedStrideMatrixIterator.h.

Public Types

• enum
• enum
• typedef vctFixedStrideMatrixConstIterator<
  _elementType, _columnStride,
  _numColumns, _rowStride > ThisType
• typedef std::iterator< std::random_access_iterator_tag,
  _elementType > BaseType
• typedef BaseType::iterator_category iterator_category

Public Member Functions

• vctFixedStrideMatrixConstIterator ()
• vctFixedStrideMatrixConstIterator (value_type *dataPtr, index_type initialColumn=0)
• vctFixedStrideMatrixConstIterator (const value_type *dataPtr, index_type initialColumn=0)
• ThisType & operator++ ()
• ThisType operator++ (int)
• ThisType & operator-- ()
• ThisType operator-- (int)
• ThisType & operator+= (difference_type difference)
• ThisType & operator-= (difference_type difference)
• difference_type operator- (const ThisType &other) const
• const value_type & operator[] (difference_type index) const
• const value_type & operator * () const
• bool operator< (const ThisType &other) const
• bool operator== (const ThisType &other) const
• bool operator> (const ThisType &other) const
• bool operator!= (const ThisType &other) const

Public Attributes

• _elementType

Protected Types

• enum

Protected Member Functions

• void WrapToRight ()
• void WrapToLeft ()

Protected Attributes

• value_type * DataPtr
• difference_type CurrentColumn

---

Member Typedef Documentation

template<class _elementType, vct::stride_type _columnStride, vct::size_type _numColumns, vct::stride_type _rowStride>

typedef vctFixedStrideMatrixConstIterator<_elementType, _columnStride, _numColumns, _rowStride> vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::ThisType

The type of the iterator itself.

Reimplemented in vctFixedStrideMatrixIterator< _elementType, _columnStride, _numColumns, _rowStride >.

Definition at line 99 of file vctFixedStrideMatrixIterator.h.

template<class _elementType, vct::stride_type _columnStride, vct::size_type _numColumns, vct::stride_type _rowStride>

typedef std::iterator<std::random_access_iterator_tag, _elementType> vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::BaseType

Base type for this iterator, i.e. std::iterator.

Reimplemented in vctFixedStrideMatrixIterator< _elementType, _columnStride, _numColumns, _rowStride >.

Definition at line 102 of file vctFixedStrideMatrixIterator.h.

template<class _elementType, vct::stride_type _columnStride, vct::size_type _numColumns, vct::stride_type _rowStride>

typedef BaseType::iterator_category vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::iterator_category

Type (i.e. category) of iterator, i.e. std::random_access_iterator_tag.

Definition at line 106 of file vctFixedStrideMatrixIterator.h.

---

Constructor & Destructor Documentation

template<class _elementType, vct::stride_type _columnStride, vct::size_type _numColumns, vct::stride_type _rowStride>

vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::vctFixedStrideMatrixConstIterator

(

)

[inline]

Default constructor: create an uninitialized object

Definition at line 144 of file vctFixedStrideMatrixIterator.h.

References CMN_ASSERT.

template<class _elementType, vct::stride_type _columnStride, vct::size_type _numColumns, vct::stride_type _rowStride>

vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::vctFixedStrideMatrixConstIterator	(	value_type *	dataPtr,
		index_type	initialColumn = 0
	)			[inline, explicit]

Constructor taking a non-const element pointer. Note that only read operations will be performed! The initial column position is assumed to be zero by default, but may be chosen otherwise (within the proper range).

Parameters:

	dataPtr	data pointer
	initialColumn	column index where the iterator is initialized

Definition at line 157 of file vctFixedStrideMatrixIterator.h.

References CMN_ASSERT.

template<class _elementType, vct::stride_type _columnStride, vct::size_type _numColumns, vct::stride_type _rowStride>

vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::vctFixedStrideMatrixConstIterator	(	const value_type *	dataPtr,
		index_type	initialColumn = 0
	)			[inline, explicit]

Constructor taking a const element pointer. We need it in order to deal with const containers being refered by this iterator. We have to perform const_cast to convert back to the stored non-const member pointer of this iterator. However, the non-const iterator class completely shadows the constructors of the const-iterator base class, and so we don't have to worry about creating a non-const iterator over a const container.

Parameters:

	dataPtr	const data pointer
	initialColumn	column index where the iterator is initialized

Definition at line 177 of file vctFixedStrideMatrixIterator.h.

References CMN_ASSERT.

---

Member Function Documentation

template<class _elementType, vct::stride_type _columnStride, vct::size_type _numColumns, vct::stride_type _rowStride>

void vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::WrapToRight

(

)

[inline, protected]

An auxiliary method to wrap the column index of the iterator. If the current column exceeds the number of columns in the matrix, more one row down and wrap to the corresponding column starting from the left

Definition at line 122 of file vctFixedStrideMatrixIterator.h.

References vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::CurrentColumn, and vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::DataPtr.

Referenced by vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::operator++(), vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::operator+=(), and vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::operator-=().

template<class _elementType, vct::stride_type _columnStride, vct::size_type _numColumns, vct::stride_type _rowStride>

void vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::WrapToLeft

(

)

[inline, protected]

An auxiliary method to wrap the column index of the iterator. If the current column is negative, move one row up, and wrap to the corresponding column starting from the right

Definition at line 134 of file vctFixedStrideMatrixIterator.h.

References vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::CurrentColumn, and vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::DataPtr.

Referenced by vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::operator+=(), vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::operator--(), and vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::operator-=().

template<class _elementType, vct::stride_type _columnStride, vct::size_type _numColumns, vct::stride_type _rowStride>

ThisType& vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::operator++

(

)

[inline]

Pre-increment.

Definition at line 187 of file vctFixedStrideMatrixIterator.h.

References vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::CurrentColumn, vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::DataPtr, and vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::WrapToRight().

template<class _elementType, vct::stride_type _columnStride, vct::size_type _numColumns, vct::stride_type _rowStride>

ThisType vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::operator++

(

int

)

[inline]

Post-increment.

Definition at line 196 of file vctFixedStrideMatrixIterator.h.

template<class _elementType, vct::stride_type _columnStride, vct::size_type _numColumns, vct::stride_type _rowStride>

ThisType& vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::operator--

(

)

[inline]

Pre-decrement.

Definition at line 204 of file vctFixedStrideMatrixIterator.h.

References vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::CurrentColumn, vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::DataPtr, and vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::WrapToLeft().

template<class _elementType, vct::stride_type _columnStride, vct::size_type _numColumns, vct::stride_type _rowStride>

ThisType vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::operator--

(

int

)

[inline]

Post-decrement.

Definition at line 213 of file vctFixedStrideMatrixIterator.h.

template<class _elementType, vct::stride_type _columnStride, vct::size_type _numColumns, vct::stride_type _rowStride>

ThisType& vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::operator+=

(

difference_type

difference

)

[inline]

Increment by offset.

Parameters:

difference

offset to increment by

Definition at line 223 of file vctFixedStrideMatrixIterator.h.

References vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::CurrentColumn, vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::DataPtr, vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::WrapToLeft(), and vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::WrapToRight().

template<class _elementType, vct::stride_type _columnStride, vct::size_type _numColumns, vct::stride_type _rowStride>

ThisType& vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::operator-=

(

difference_type

difference

)

[inline]

Decrement by offset.

Parameters:

difference

offset to decrement by

Definition at line 238 of file vctFixedStrideMatrixIterator.h.

References vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::CurrentColumn, vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::DataPtr, vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::WrapToLeft(), and vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::WrapToRight().

template<class _elementType, vct::stride_type _columnStride, vct::size_type _numColumns, vct::stride_type _rowStride>

difference_type vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::operator-

(

const ThisType &

other

)

const [inline]

Subtraction between iterators returns the number of increments needed for the second operand to reach the first operand, if it is reachable.

The number of increments is found by the following equations: DataPtr - (difference / NUM_COLUMNS) * ROW_STRIDE + (difference % NUM_COLUMNS) * COL_STRIDE == other.DataPtr DataPtr - other.DataPtr == (difference / NUM_COLUMNS) * ROW_STRIDE + (difference % NUM_COLUMNS) * COL_STRIDE

if (ROW_STRIDE >= NUM_COLUMNS * COL_STRIDE) { (DataPtr - other.DataPtr) / ROW_STRIDE == row_diff == (difference / NUM_COLUMNS) DataPtr - other.DataPtr - row_diff * ROW_STRIDE == (difference % NUM_COLUMNS) * COL_STRIDE (DataPtr - other.DataPtr - row_diff * ROW_STRIDE) / COL_STRIDE == col_diff == (difference % NUM_COLUMNS) difference == row_diff * NUM_COLUMNS + col_diff } otherwise switch the roles of rows and columns.

Note:

this operation assumes reachability and does not test for it.

Definition at line 267 of file vctFixedStrideMatrixIterator.h.

References vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::CurrentColumn, and vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::DataPtr.

template<class _elementType, vct::stride_type _columnStride, vct::size_type _numColumns, vct::stride_type _rowStride>

const value_type& vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::operator[]

(

difference_type

index

)

const [inline]

Random access (return const reference).

Definition at line 278 of file vctFixedStrideMatrixIterator.h.

template<class _elementType, vct::stride_type _columnStride, vct::size_type _numColumns, vct::stride_type _rowStride>

const value_type& vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::operator *

(

)

const [inline]

Dereference (const).

Definition at line 286 of file vctFixedStrideMatrixIterator.h.

References vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::DataPtr.

template<class _elementType, vct::stride_type _columnStride, vct::size_type _numColumns, vct::stride_type _rowStride>

bool vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::operator<

(

const ThisType &

other

)

const [inline]

Order relation between iterators, required by STL.

Note:

The STL manual states that "if j is reachable from i then i<j". This does not imply the converse: "if i<j then j is reachable from i". In the case here, the converse does not hold.

Definition at line 298 of file vctFixedStrideMatrixIterator.h.

template<class _elementType, vct::stride_type _columnStride, vct::size_type _numColumns, vct::stride_type _rowStride>

bool vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::operator==

(

const ThisType &

other

)

const [inline]

Equality of iterators, required by STL.

Definition at line 304 of file vctFixedStrideMatrixIterator.h.

References vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::CurrentColumn, and vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::DataPtr.

template<class _elementType, vct::stride_type _columnStride, vct::size_type _numColumns, vct::stride_type _rowStride>

bool vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::operator>

(

const ThisType &

other

)

const [inline]

Complementary operation to operator <.

Definition at line 310 of file vctFixedStrideMatrixIterator.h.

template<class _elementType, vct::stride_type _columnStride, vct::size_type _numColumns, vct::stride_type _rowStride>

bool vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::operator!=

(

const ThisType &

other

)

const [inline]

Complementary operation to operator ==.

Definition at line 316 of file vctFixedStrideMatrixIterator.h.

---

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

• vctFixedStrideMatrixIterator.h

---