A base class for Lattice iterators. More...

#include <LatticeIterInterface.h>

Inheritance diagram for casa::LatticeIterInterface< T >:

Public Member Functions
	LatticeIterInterface (const Lattice< T > &lattice, const LatticeNavigator &navigator, Bool useRef)
	Construct with the given navigator.
virtual	~LatticeIterInterface ()
	A virtual destructor.
Protected Member Functions
	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++ ()
	Increment operator - increment the cursor to the next position.
Bool	operator++ (int)
Bool	operator-- ()
	Decrement operator - decrement the cursor to the previous position.
Bool	operator-- (int)
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).
IPosition	position () const
	Function which returns the current position of the beginning of the cursor within the Lattice.
IPosition	endPosition () const
	Function which returns the current position of the end of the cursor.
IPosition	latticeShape () const
	Function which returns the shape of the Lattice being iterated through.
IPosition	cursorShape () const
	Function which returns the shape of the cursor which is iterating through the Lattice.
virtual Vector< T > &	vectorCursor (Bool doRead, Bool autoRewrite)
	Functions which returns a window to the data in the Lattice.
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
	Function which checks the internals of the class for consistency.
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.
Protected Attributes
LatticeNavigator *	itsNavPtr
	Pointer to the method of Lattice transversal.
Lattice< T > *	itsLattPtr
	Pointer to the Lattice.
Array< T >	itsBuffer
	A buffer to hold the data.
Array< T > *	itsCurPtr
	Polymorphic pointer to the data in itsCursor.
Array< T >	itsCursor
	An Array which references the same data as the itsCurPtr, but has all the degenerate axes.
Bool	itsUseRef
	Keep a reference to the data (if possible).
Bool	itsIsRef
	Is the cursor a reference to the lattice?
Bool	itsHaveRead
	Have the data been read after a cursor update? (False=not read)
Bool	itsRewrite
	Rewrite the cursor data before moving or destructing?
IPosition	itsCursorAxes
	The axes forming the cursor.
Friends
class	Lattice< T >
class	LatticeIterator< T >
class	RO_LatticeIterator< T >

Detailed Description

template<class T>
class casa::LatticeIterInterface< T >

A base class for Lattice iterators.

Intended use:

Internal

Review Status

Reviewed By:: Peter Barnes
Date Reviewed:: 1999/10/30
Test programs:: tLatticeIterator

Prerequisite

letter/envelope schemes - see Coplien, "Advanced C++", ch 5.5
Lattice
LatticeIterator

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.

Definition at line 116 of file LatticeIterInterface.h.

Constructor & Destructor Documentation

template<class T>

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

Construct with the given navigator.

template<class T>

virtual casa::LatticeIterInterface< T >::~LatticeIterInterface ( ) [virtual]

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.

template<class T>

casa::LatticeIterInterface< T >::LatticeIterInterface ( ) [protected]

Default constructor (for derived classes).

template<class T>

casa::LatticeIterInterface< T >::LatticeIterInterface ( const LatticeIterInterface< T > & other ) [protected]

Copy constructor (copy semantics).

Member Function Documentation

template<class T>

void casa::LatticeIterInterface< T >::allocateBuffer ( ) [protected]

Allocate the internal buffer.

template<class T>

void casa::LatticeIterInterface< T >::allocateCurPtr ( ) [protected]

Allocate the nondegenerate array with the correct type.

template<class T >

Bool casa::LatticeIterInterface< T >::atEnd ( ) const [inline, protected]

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

Definition at line 293 of file LatticeIterInterface.h.

template<class T >

Bool casa::LatticeIterInterface< T >::atStart ( ) const [inline, protected]

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

Definition at line 287 of file LatticeIterInterface.h.

template<class T>

virtual LatticeIterInterface<T>* casa::LatticeIterInterface< T >::clone ( ) const [protected, virtual]

Clone the object.

Reimplemented in casa::HDF5LattIter< T >, and casa::PagedArrIter< T >.

template<class T>

void casa::LatticeIterInterface< T >::copyBase ( const LatticeIterInterface< T > & other ) [protected]

Copy the base data of the other object.

template<class T>

virtual Cube<T>& casa::LatticeIterInterface< T >::cubeCursor	(	Bool	doRead,
		Bool	autoRewrite
	)		`[protected, virtual]`

template<class T>

virtual Array<T>& casa::LatticeIterInterface< T >::cursor	(	Bool	doRead,
		Bool	autoRewrite
	)		`[protected, virtual]`

template<class T >

IPosition casa::LatticeIterInterface< T >::cursorShape ( ) const [inline, protected]

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.

Definition at line 323 of file LatticeIterInterface.h.

template<class T>

virtual void casa::LatticeIterInterface< T >::cursorUpdate ( ) [protected, virtual]

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

template<class T >

IPosition casa::LatticeIterInterface< T >::endPosition ( ) const [inline, protected]

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.

Definition at line 311 of file LatticeIterInterface.h.

template<class T>

Lattice<T>& casa::LatticeIterInterface< T >::lattice ( ) [inline, protected]

Return the underlying lattice.

Definition at line 147 of file LatticeIterInterface.h.

template<class T >

IPosition casa::LatticeIterInterface< T >::latticeShape ( ) const [inline, protected]

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.

Definition at line 317 of file LatticeIterInterface.h.

template<class T>

virtual Matrix<T>& casa::LatticeIterInterface< T >::matrixCursor	(	Bool	doRead,
		Bool	autoRewrite
	)		`[protected, virtual]`

template<class T >

uInt casa::LatticeIterInterface< T >::nsteps ( ) const [inline, protected]

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.

Definition at line 299 of file LatticeIterInterface.h.

template<class T>

Bool casa::LatticeIterInterface< T >::ok ( ) const [protected]

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.

template<class T >

Bool casa::LatticeIterInterface< T >::operator++ ( ) [inline, protected]

Increment operator - increment the cursor to the next position.

The implementation of the prefix operator calls the postfix one.

Definition at line 277 of file LatticeIterInterface.h.

template<class T>

Bool casa::LatticeIterInterface< T >::operator++ ( int ) [protected]

template<class T >

Bool casa::LatticeIterInterface< T >::operator-- ( ) [inline, protected]

Decrement operator - decrement the cursor to the previous position.

The implementation of the prefix operator calls the postfix one.

Definition at line 282 of file LatticeIterInterface.h.

template<class T>

Bool casa::LatticeIterInterface< T >::operator-- ( int ) [protected]

template<class T>

LatticeIterInterface& casa::LatticeIterInterface< T >::operator= ( const LatticeIterInterface< T > & other ) [protected]

Assignment (copy semantics).

template<class T >

IPosition casa::LatticeIterInterface< T >::position ( ) const [inline, protected]

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.

Definition at line 305 of file LatticeIterInterface.h.

template<class T>

virtual void casa::LatticeIterInterface< T >::readData ( Bool doRead ) [protected, virtual]

Do the actual read of the data.

template<class T>

void casa::LatticeIterInterface< T >::reset ( ) [protected]

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

template<class T>

virtual void casa::LatticeIterInterface< T >::rewriteData ( ) [protected, virtual]

Rewrite the cursor data and clear the rewrite flag.

template<class T>

void casa::LatticeIterInterface< T >::setCurPtr2Cursor ( ) [protected]

Synchronise the storage of itsCurPtr with itsCursor.

template<class T>

virtual Vector<T>& casa::LatticeIterInterface< T >::vectorCursor	(	Bool	doRead,
		Bool	autoRewrite
	)		`[protected, virtual]`

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).

Friends And Related Function Documentation

template<class T>

friend class Lattice< T > [friend]

Definition at line 118 of file LatticeIterInterface.h.

template<class T>

friend class LatticeIterator< T > [friend]

Definition at line 119 of file LatticeIterInterface.h.

template<class T>

friend class RO_LatticeIterator< T > [friend]

Definition at line 120 of file LatticeIterInterface.h.

Member Data Documentation

template<class T>

Array<T> casa::LatticeIterInterface< T >::itsBuffer [protected]

A buffer to hold the data.

Usually itsCursor shares the data with this buffer, but for an ArrayLattice itsCursor might reference the lattice directly instead of making a copy in the buffer.

Definition at line 255 of file LatticeIterInterface.h.

template<class T>

Array<T>* casa::LatticeIterInterface< T >::itsCurPtr [protected]

Polymorphic pointer to the data in itsCursor.

Definition at line 257 of file LatticeIterInterface.h.

template<class T>

Array<T> casa::LatticeIterInterface< T >::itsCursor [protected]

An Array which references the same data as the itsCurPtr, but has all the degenerate axes.

This is an optimization to avoid the overhead of having to add the degenerate axes for each iteration.

Definition at line 261 of file LatticeIterInterface.h.

template<class T>

IPosition casa::LatticeIterInterface< T >::itsCursorAxes [protected]