LatticeIterInterface.h

The LatticeIterInterface class defines an abstract base for the standard methods of iteration required by Lattices. Declaring an Iterator that is derived from this class forces it to meet the virtual requirements.

The author of a Lattice derived class should consider the following:

The LatticeStepper class has strong effects on how the cursor is filled. A non-integral shape of the cursor may allow a step of iteration to be only partially "touching" the Lattice. We have dubbed this "hangover."
If the cursor has "hangover" it should be filled with a value that indicates the cursor is in undefined space.
The cursor cannot be a reference to a part of the Lattice since hangover would imply a reference to undefined memory. To enclose the Lattice with a zero valued hangover buffer would be inefficient. The method thus forced upon the programmer is to "update" the cursor with Lattice values after each move or iteration and to "write" the possibly changed cursor values back into the Lattice before each iteration. An algorithm which does the cursor update/write actions (and is independent of Lattice dimensionality) may be copied from ArrLatticeIter::cursorUpdate() and ArrLatticeIter::cursorWrite(), respectively.
The majority of the code in a new letter for LatticeIterator may be cut and pasted from other implementations of letters. See ArrLatticeIter or PagedArrIter.

Example

For an example see LatticeIterator.

Motivation

The is class provides a tidy base for letter/envelope techniques of iteration.

To Do

IPositions are returned by value. This a reflection of the LatticeNavigator base class' inability to predict the availibility of data members for references.

Member Description

LatticeIterInterface (const Lattice<T>& lattice, const LatticeNavigator& navigator, Bool useRef)

Construct with the given navigator.

virtual ~LatticeIterInterface()

A virtual destructor. A virtual is needed to ensure that derived classes declared as pointers to a LatticeIterInterface will scope their destructor to the derived class destructor.

LatticeIterInterface()

Default constructor (for derived classes).

LatticeIterInterface (const LatticeIterInterface<T>& other)

Copy constructor (copy semantics).

LatticeIterInterface& operator= (const LatticeIterInterface<T>& other)

Assignment (copy semantics).

virtual LatticeIterInterface<T>* clone() const

Clone the object.

Lattice<T>& lattice()

Return the underlying lattice.

Bool operator++()
Bool operator++(int)

Increment operator - increment the cursor to the next position. The implementation of the prefix operator calls the postfix one.

Bool operator--()
Bool operator--(int)

Decrement operator - decrement the cursor to the previous position. The implementation of the prefix operator calls the postfix one.

void reset()

Function which resets the cursor to the beginning of the Lattice and resets the number of steps taken to zero.

Bool atStart() const

Function which returns a value of "True" if the cursor is at the beginning of the Lattice, otherwise, returns "False"

Bool atEnd() const

Function which returns "True" if the cursor has been incremented to the end of the lattice, otherwise, returns "False"

uInt nsteps() const

Function to return the number of steps (increments or decrements) taken since construction (or since last reset). This is a running count of all cursor movement since doing N increments followed by N decrements does not necessarily put the cursor back at the origin of the Lattice.

IPosition position() const

Function which returns the current position of the beginning of the cursor within the Lattice. The returned IPosition will have the same number of axes as the underlying Lattice.

IPosition endPosition() const

Function which returns the current position of the end of the cursor. The returned IPosition will have the same number of axes as the underlying Lattice.

IPosition latticeShape() const

Function which returns the shape of the Lattice being iterated through. The returned IPosition will always have the same number of axes as the underlying Lattice.

IPosition cursorShape() const

Function which returns the shape of the cursor which is iterating through the Lattice. The cursor will always have as many dimensions as the Lattice.

virtual Vector<T>& vectorCursor (Bool doRead, Bool autoRewrite)
virtual Matrix<T>& matrixCursor (Bool doRead, Bool autoRewrite)
virtual Cube<T>& cubeCursor (Bool doRead, Bool autoRewrite)
virtual Array<T>& cursor (Bool doRead, Bool autoRewrite)

Functions which returns a window to the data in the Lattice. These are used to read the data within the Lattice. Use the function that is appropriate to the current cursor dimension, AFTER REMOVING DEGENERATE AXES, or use the cursor function which works with any number of dimensions in the cursor. A call of the function whose return value is inappropriate with respect to the current cursor dimension will throw an exception (AipsError).
The doRead flag indicates if the data need to be read or if only a cursor with the correct shape has to be returned.
The autoRewrite flag indicates if the data has to be rewritten when the iterator state changes (e.g. moved, destructed).

Bool ok() const

Function which checks the internals of the class for consistency. Returns True if everything is fine otherwise returns False. The default implementation of this function always returns True.

virtual void readData (Bool doRead)

Do the actual read of the data.

virtual void rewriteData()

Rewrite the cursor data and clear the rewrite flag.

virtual void cursorUpdate()

Update the cursor for the next chunk of data (resize if needed).

void allocateBuffer()

Allocate the internal buffer.

void allocateCurPtr()

Allocate the nondegenerate array with the correct type.

void setCurPtr2Cursor()

Synchronise the storage of itsCurPtr with itsCursor.

void copyBase (const LatticeIterInterface<T>& other)

Copy the base data of the other object.