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

Matrix iterator. More...

#include <vctFixedStrideMatrixIterator.h>

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

Public Types
enum	{ COL_STRIDE = _columnStride , ROW_STRIDE = _rowStride }
enum	{ NUM_COLUMNS = _numColumns }
typedef vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >	ThisType
typedef std::random_access_iterator_tag	iterator_category

Public Member Functions
	VCT_CONTAINER_TRAITS_TYPEDEFS (_elementType)
	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
bool	operator>= (const ThisType &other) const
bool	operator!= (const ThisType &other) const

Protected Types
enum	{ ROW_FIRST_INDEX = (ROW_STRIDE >= NUM_COLUMNS * COL_STRIDE) }

Protected Member Functions
void	WrapToRight ()
void	WrapToLeft ()

Protected Attributes
value_type *	DataPtr
difference_type	CurrentColumn

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.

Member Typedef Documentation

iterator_category

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

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

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

ThisType

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.

Member Enumeration Documentation

anonymous enum

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

anonymous enum

Enumerator
COL_STRIDE
ROW_STRIDE

anonymous enum

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

anonymous enum

protected

Enumerator
ROW_FIRST_INDEX

anonymous enum

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

anonymous enum

Enumerator
NUM_COLUMNS

Constructor & Destructor Documentation

vctFixedStrideMatrixConstIterator() [1/3]

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

vctFixedStrideMatrixConstIterator() [2/3]

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 )

inlineexplicit

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

vctFixedStrideMatrixConstIterator() [3/3]

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 )

inlineexplicit

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

Member Function Documentation

operator!=()

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 ==.

operator*()

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).

operator++() [1/2]

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.

operator++() [2/2]

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.

operator+=()

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

operator-()

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.

operator--() [1/2]

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.

operator--() [2/2]

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.

operator-=()

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

operator<()

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.

operator<=()

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

operator==()

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.

operator>()

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 <.

operator>=()

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

operator[]()

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).

VCT_CONTAINER_TRAITS_TYPEDEFS()

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

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

(

_elementType

)

WrapToLeft()

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

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

inlineprotected

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

WrapToRight()

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

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

inlineprotected

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

Member Data Documentation

CurrentColumn

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

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

protected

DataPtr

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

value_type* vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::DataPtr

protected

---

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

• tmp/cisst-saw/cisst/cisstVector/vctFixedStrideMatrixIterator.h