ArrayPosIter.h

ArrayPositionIterator manipulates an IPosition "cursor" through some volume defined by an origin and shape. This position can in turn be used to index into, or otherwise define a position in, an Array. Normally users won't use this class directly, rather they will use an ArrayIterator, VectorIterator or MatrixIterator object, which in turn uses this class. ArrayPositionIterator is also used in the implementation of Array.

    template<class T> void verySlowArrayCopy(Array<T> &to, const Array<T> &from)
    {
        if (! to.conform(from)) {
           // throw some error
        }
        ArrayPositionIterator toiter(to.shape(), to.origin(),0);
        ArrayPositionIterator fromiter(from.shape(), from.origin(),0);
        // If to.origin() == from.origin() we only need one iterator
        // or we could offset positions by the difference in origins.
        // The "0" means we are stepping by scalars.
        while (! toiter.pastEnd()) {    // we know arrays conform
            to(toiter.pos()) = fromiter(fromiter.pos());
            toiter.next(); fromiter.next();
        }
    }

Iteration can be done by any combination of axes, but it can only be done for full axes.
The iteration step always "fills up" its dimensionality. E.g., if we are stepping through a cube by matrices, the matrix completely fills up the plane. Class ArrayLattice in the lattices package can be used to iterate with partial volumes.

All the array iterator classes should probably be reimplemented; their implementation is a bit ugly.

Member Description

ArrayPositionIterator(const IPosition &shape, const IPosition &origin, uInt byDim)
ArrayPositionIterator(const IPosition &shape, uInt byDim)

Define the shape and origin of the volume the cursor will step through. Also define the dimensionality of the step. byDim==0 implies we are stepping by scalars (i.e. every element), byDim==1 implies that we are stepping by vector, ==2 by matrices, and so on. If uses the first byDim axes as the cursor volume and it steps through the remaining axes.

ArrayPositionIterator(const IPosition &shape, const IPosition &axes, Bool axesAreCursor=True)

Step through an array using the given axes. The axes can be given in two ways:

axesAreCursor=True means that the axes form the cursor axes. The remaining axes will form the iteration axes. This is the default.
axesAreCursor=False means the opposite. In this case the iteration axes can be given in any order.

E.g. when using iteration axes 2,0 for an array with shape [5,3,7], each iteration step returns a cursor (containing the data of axis 1). During the iteration axis 2 will vary most rapidly (as it was given first). Iterate over the given axes in the given order. The cursor axes are the remaining axes. E.g. for a shape of [3,4,5,6] and iterAxes [3,1], the cursor size is [3,5] (axes 0 and 2), while the iteration is fastest for axis 3.