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.
template<class _elementType, vct::stride_type _columnStride, vct::size_type _numColumns, vct::stride_type _rowStride>
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.
1.8.6