LatticeIterInterface.h
Classes
- LatticeIterInterface -- A base class for Lattice iterators (full description)
Interface
- Public Members
- LatticeIterInterface (const Lattice<T>& lattice, const LatticeNavigator& navigator, Bool useRef)
- virtual ~LatticeIterInterface()
- Protected Members
- LatticeIterInterface()
- LatticeIterInterface (const LatticeIterInterface<T>& other)
- LatticeIterInterface& operator= (const LatticeIterInterface<T>& other)
- virtual LatticeIterInterface<T>* clone() const
- Lattice<T>& lattice()
- Bool operator++()
- Bool operator++(int)
- Bool operator--()
- Bool operator--(int)
- void reset()
- Bool atStart() const
- Bool atEnd() const
- uInt nsteps() const
- IPosition position() const
- IPosition endPosition() const
- IPosition latticeShape() const
- IPosition cursorShape() const
- 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)
- Bool ok() const
- virtual void readData (Bool doRead)
- virtual void rewriteData()
- virtual void cursorUpdate()
- void allocateBuffer()
- void allocateCurPtr()
- void setCurPtr2Cursor()
- void copyBase (const LatticeIterInterface<T>& other)
Review Status
- Reviewed By:
- Peter Barnes
- Date Reviewed:
- 1999/10/30
- Programs:
- Tests:
Prerequisite
Etymology
The LatticeIterInterface class name reflects its role as the abstract
base class for concrete read-write LatticeIterators
Synopsis
This class is only for authors of Lattice letters for the LatticeIterator
envelope. General users should see LatticeIterator.
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.
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.
Default constructor (for derived classes).
Copy constructor (copy semantics).
LatticeIterInterface& operator= (const LatticeIterInterface<T>& other)
Assignment (copy semantics).
virtual LatticeIterInterface<T>* clone() const
Clone the object.
Return the underlying lattice.
Increment operator - increment the cursor to the next position. The
implementation of the prefix operator calls the postfix one.
Decrement operator - decrement the cursor to the previous position. The
implementation of the prefix operator calls the postfix one.
Function which resets the cursor to the beginning of the Lattice and
resets the number of steps taken to zero.
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.
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.
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.
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.
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.
Rewrite the cursor data and clear the rewrite flag.
Update the cursor for the next chunk of data (resize if needed).
Allocate the internal buffer.
Allocate the nondegenerate array with the correct type.
Synchronise the storage of itsCurPtr with itsCursor.
void copyBase (const LatticeIterInterface<T>& other)
Copy the base data of the other object.