Iterate an IPosition through the shape of an Array. More...

#include <ArrayPosIter.h>

Inheritance diagram for casa::ArrayPositionIterator:

Public Member Functions
	ArrayPositionIterator (const IPosition &shape, const IPosition &origin, uInt byDim)
	Define the shape and origin of the volume the cursor will step through.
	ArrayPositionIterator (const IPosition &shape, uInt byDim)
	ArrayPositionIterator (const IPosition &shape, const IPosition &axes, Bool axesAreCursor=True)
	Step through an array using the given axes.
virtual	~ArrayPositionIterator ()
virtual void	reset ()
	Reset the cursor to the beginning of the volume.
void	origin ()
Bool	atStart () const
	Returns true of the cursor is at the origin.
Bool	pastEnd () const
	Returns true if the cursor has moved past the end of its volume.
const IPosition &	pos () const
	Return the position of the cursor.
IPosition	endPos () const
	Return the end position of the cursor.
virtual void	next ()
	Advance the cursor to its next position.
virtual void	set (const IPosition &cursorPos)
	Set the cursor to the given position.
uInt	ndim () const
	What is the dimensionality of the volume we are iterating through?
const IPosition &	iterAxes () const
	Return the iteration axes.
const IPosition &	cursorAxes () const
	Return the cursor axes.
virtual ArrayBase &	getArray ()
	Get the array in the cursor.
Protected Member Functions
uInt	nextStep ()
	Advance cursor to its next position and tell which dimension stepped.
uInt	dimIter () const
	What is the dimensionality of the "step" the cursor takes, i.e.
Private Member Functions
void	setup (uInt byDim)
	Setup the object for the constructor.
void	setup (const IPosition &axes, Bool axesAreCursor)
Private Attributes
IPosition	Start

IPosition	Shape
IPosition	End
IPosition	Cursor
Bool	atOrBeyondEnd
IPosition	cursAxes
IPosition	iterationAxes

Detailed Description

Iterate an IPosition through the shape of an Array.

Review Status

Reviewed By:: UNKNOWN
Date Reviewed:: before2004/08/25

<h3>Synopsis</h3>
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.

ArrayPositionIterator also serves as the base class of ArrayIterator. Function makeIterator in class ArrayBase can be used to make an ArrayIterator without having to know the template type. Function getArray in this class can be used to obtain the current contents of the cursor as an ArrayBase object.

Definition at line 87 of file ArrayPosIter.h.

Constructor & Destructor Documentation

casa::ArrayPositionIterator::ArrayPositionIterator	(	const IPosition &	shape,
		const IPosition &	origin,
		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.

casa::ArrayPositionIterator::ArrayPositionIterator	(	const IPosition &	shape,
		uInt	byDim
	)

casa::ArrayPositionIterator::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).
E.g. for a shape of [3,4,5,6] and cursor axes [2,0], the cursor size is [3,5] (axes 0 and 2), while the iteration is done over axes 1 and 3 (1 the fastest varying one).

virtual casa::ArrayPositionIterator::~ArrayPositionIterator ( ) [inline, virtual]

Definition at line 123 of file ArrayPosIter.h.

Member Function Documentation

Bool casa::ArrayPositionIterator::atStart ( ) const

Returns true of the cursor is at the origin.

const IPosition& casa::ArrayPositionIterator::cursorAxes ( ) const [inline]

Return the cursor axes.

Definition at line 165 of file ArrayPosIter.h.

References cursAxes.

uInt casa::ArrayPositionIterator::dimIter ( ) const [inline, protected]

What is the dimensionality of the "step" the cursor takes, i.e.

0 for scalars, 1 for vector, ....

Definition at line 177 of file ArrayPosIter.h.

References cursAxes, and casa::IPosition::nelements().

IPosition casa::ArrayPositionIterator::endPos ( ) const

Return the end position of the cursor.

virtual ArrayBase& casa::ArrayPositionIterator::getArray ( ) [virtual]

Get the array in the cursor.

This is only implemented in the derived ArrayIterator class. By default it throws an exception.

Reimplemented in casa::ArrayIterator< T >.

const IPosition& casa::ArrayPositionIterator::iterAxes ( ) const [inline]

Return the iteration axes.

Definition at line 162 of file ArrayPosIter.h.

References iterationAxes.

uInt casa::ArrayPositionIterator::ndim ( ) const [inline]

What is the dimensionality of the volume we are iterating through?

Dimensionality of the array we are iterating through.

Definition at line 193 of file ArrayPosIter.h.

References casa::IPosition::nelements(), and Start.

virtual void casa::ArrayPositionIterator::next ( ) [virtual]

Advance the cursor to its next position.

Reimplemented in casa::ArrayIterator< T >.

uInt casa::ArrayPositionIterator::nextStep ( ) [protected]

Advance cursor to its next position and tell which dimension stepped.

void casa::ArrayPositionIterator::origin ( ) [inline]

Definition at line 128 of file ArrayPosIter.h.

References reset().

Bool casa::ArrayPositionIterator::pastEnd ( ) const [inline]

Returns true if the cursor has moved past the end of its volume.

We are at the "end" if we cannot advance any more.

Definition at line 199 of file ArrayPosIter.h.

References atOrBeyondEnd.

const IPosition& casa::ArrayPositionIterator::pos ( ) const [inline]

Return the position of the cursor.

This include all axes

Definition at line 140 of file ArrayPosIter.h.

References Cursor.

virtual void casa::ArrayPositionIterator::reset ( ) [virtual]

Reset the cursor to the beginning of the volume.

Reimplemented in casa::ArrayIterator< T >.

Referenced by origin().

virtual void casa::ArrayPositionIterator::set ( const IPosition & cursorPos ) [virtual]

Set the cursor to the given position.

The position can only contain the iteration axes or it can be the full position.
In the first case the position must to be given in the order of the iteration axes as given in the constructor. In the latter case the position must be given in natural order (as given by function pos and only the cursor axes are taken into account.

Reimplemented in casa::ArrayIterator< T >.

void casa::ArrayPositionIterator::setup ( uInt byDim ) [private]

Setup the object for the constructor.