A base class for Lattice iterators. More...

#include <ImageExpr.h>

Inheritance diagram for casacore::LatticeIterInterface< T >:

Public Member Functions
	LatticeIterInterface (const Lattice< T > &lattice, const LatticeNavigator &navigator, Bool useRef)
	Construct with the given navigator. More...

virtual	~LatticeIterInterface ()
	A virtual destructor. More...

Protected Member Functions
	LatticeIterInterface ()
	Default constructor (for derived classes). More...

	LatticeIterInterface (const LatticeIterInterface< T > &other)
	Copy constructor (copy semantics). More...

LatticeIterInterface &	operator= (const LatticeIterInterface< T > &other)
	Assignment (copy semantics). More...

virtual LatticeIterInterface< T > *	clone () const
	Clone the object. More...

Lattice< T > &	lattice ()
	Return the underlying lattice. More...

Bool	operator++ ()
	Increment operator - increment the cursor to the next position. More...

Bool	operator++ (int)

Bool	operator-- ()
	Decrement operator - decrement the cursor to the previous position. More...

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

Bool	atStart () const
	Function which returns a value of "True" if the cursor is at the beginning of the Lattice, otherwise, returns "False". More...

Bool	atEnd () const
	Function which returns "True" if the cursor has been incremented to the end of the lattice, otherwise, returns "False". More...

uInt	nsteps () const
	Function to return the number of steps (increments or decrements) taken since construction (or since last reset). More...

IPosition	position () const
	Function which returns the current position of the beginning of the cursor within the Lattice. More...

IPosition	endPosition () const
	Function which returns the current position of the end of the cursor. More...

IPosition	latticeShape () const
	Function which returns the shape of the Lattice being iterated through. More...

IPosition	cursorShape () const
	Function which returns the shape of the cursor which is iterating through the Lattice. More...

virtual Vector< T > &	vectorCursor (Bool doRead, Bool autoRewrite)
	Functions which returns a window to the data in the Lattice. More...

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

virtual void	readData (Bool doRead)
	Do the actual read of the data. More...

virtual void	rewriteData ()
	Rewrite the cursor data and clear the rewrite flag. More...

virtual void	cursorUpdate ()
	Update the cursor for the next chunk of data (resize if needed). More...

void	allocateBuffer ()
	Allocate the internal buffer. More...

void	allocateCurPtr ()
	Allocate the nondegenerate array with the correct type. More...

void	setCurPtr2Cursor ()
	Synchronise the storage of itsCurPtr with itsCursor. More...

void	copyBase (const LatticeIterInterface< T > &other)
	Copy the base data of the other object. More...

Protected Attributes
LatticeNavigator *	itsNavPtr
	Pointer to the method of Lattice transversal. More...

Lattice< T > *	itsLattPtr
	Pointer to the Lattice. More...

Array< T >	itsBuffer
	A buffer to hold the data. More...

Array< T > *	itsCurPtr
	Polymorphic pointer to the data in itsCursor. More...

Array< T >	itsCursor
	An Array which references the same data as the itsCurPtr, but has all the degenerate axes. More...

Bool	itsUseRef
	Keep a reference to the data (if possible). More...

Bool	itsIsRef
	Is the cursor a reference to the lattice? More...

Bool	itsHaveRead
	Have the data been read after a cursor update? (False=not read) More...

Bool	itsRewrite
	Rewrite the cursor data before moving or destructing? More...

IPosition	itsCursorAxes
	The axes forming the cursor. More...

Friends
class	Lattice< T >

class	LatticeIterator< T >

class	RO_LatticeIterator< T >

Detailed Description

template<class T>
class casacore::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 47 of file ImageExpr.h.

Constructor & Destructor Documentation

template<class T>

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

Construct with the given navigator.

template<class T>

virtual casacore::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>

casacore::LatticeIterInterface< T >::LatticeIterInterface ( )

protected

Default constructor (for derived classes).

template<class T>

casacore::LatticeIterInterface< T >::LatticeIterInterface ( const LatticeIterInterface< T > & other )

protected

Copy constructor (copy semantics).

Member Function Documentation

template<class T>

void casacore::LatticeIterInterface< T >::allocateBuffer ( )

protected

Allocate the internal buffer.

template<class T>

void casacore::LatticeIterInterface< T >::allocateCurPtr ( )

protected

Allocate the nondegenerate array with the correct type.

template<class T >

Bool casacore::LatticeIterInterface< T >::atEnd ( ) const

inlineprotected

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

Definition at line 290 of file LatticeIterInterface.h.

template<class T >

Bool casacore::LatticeIterInterface< T >::atStart ( ) const

inlineprotected

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

Definition at line 284 of file LatticeIterInterface.h.

template<class T>

virtual LatticeIterInterface<T>* casacore::LatticeIterInterface< T >::clone ( ) const

protectedvirtual

Clone the object.

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

template<class T>

void casacore::LatticeIterInterface< T >::copyBase ( const LatticeIterInterface< T > & other )

protected

Copy the base data of the other object.

template<class T>

virtual Cube<T>& casacore::LatticeIterInterface< T >::cubeCursor	(	Bool	doRead,
		Bool	autoRewrite
	)

protectedvirtual

template<class T>

virtual Array<T>& casacore::LatticeIterInterface< T >::cursor	(	Bool	doRead,
		Bool	autoRewrite
	)

protectedvirtual

template<class T >

IPosition casacore::LatticeIterInterface< T >::cursorShape ( ) const

inlineprotected

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 320 of file LatticeIterInterface.h.

template<class T>

virtual void casacore::LatticeIterInterface< T >::cursorUpdate ( )

protectedvirtual

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

template<class T >

IPosition casacore::LatticeIterInterface< T >::endPosition ( ) const

inlineprotected

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 308 of file LatticeIterInterface.h.

template<class T>

Lattice<T>& casacore::LatticeIterInterface< T >::lattice ( )

inlineprotected

Return the underlying lattice.

Definition at line 144 of file LatticeIterInterface.h.

References casacore::LatticeIterInterface< T >::itsLattPtr.

template<class T >

IPosition casacore::LatticeIterInterface< T >::latticeShape ( ) const

inlineprotected

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 314 of file LatticeIterInterface.h.

template<class T>

virtual Matrix<T>& casacore::LatticeIterInterface< T >::matrixCursor	(	Bool	doRead,
		Bool	autoRewrite
	)

protectedvirtual

template<class T >

uInt casacore::LatticeIterInterface< T >::nsteps ( ) const

inlineprotected

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 296 of file LatticeIterInterface.h.

template<class T>

Bool casacore::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 casacore::LatticeIterInterface< T >::operator++ ( )

inlineprotected

Increment operator - increment the cursor to the next position.

The implementation of the prefix operator calls the postfix one.

Definition at line 274 of file LatticeIterInterface.h.

template<class T>

Bool casacore::LatticeIterInterface< T >::operator++ ( int )

protected

template<class T >

Bool casacore::LatticeIterInterface< T >::operator-- ( )

inlineprotected

Decrement operator - decrement the cursor to the previous position.

The implementation of the prefix operator calls the postfix one.

Definition at line 279 of file LatticeIterInterface.h.

template<class T>

Bool casacore::LatticeIterInterface< T >::operator-- ( int )

protected

template<class T>

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

protected

Assignment (copy semantics).

template<class T >

IPosition casacore::LatticeIterInterface< T >::position ( ) const

inlineprotected

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 302 of file LatticeIterInterface.h.

template<class T>

virtual void casacore::LatticeIterInterface< T >::readData ( Bool doRead )

protectedvirtual

Do the actual read of the data.

template<class T>

void casacore::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 casacore::LatticeIterInterface< T >::rewriteData ( )

protectedvirtual

Rewrite the cursor data and clear the rewrite flag.

template<class T>

void casacore::LatticeIterInterface< T >::setCurPtr2Cursor ( )

protected

Synchronise the storage of itsCurPtr with itsCursor.

template<class T>

virtual Vector<T>& casacore::LatticeIterInterface< T >::vectorCursor	(	Bool	doRead,
		Bool	autoRewrite
	)

protectedvirtual

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 115 of file LatticeIterInterface.h.

template<class T>

friend class LatticeIterator< T >

friend

Definition at line 116 of file LatticeIterInterface.h.

template<class T>

friend class RO_LatticeIterator< T >

friend

Definition at line 117 of file LatticeIterInterface.h.

Member Data Documentation

template<class T>

Array<T> casacore::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 252 of file LatticeIterInterface.h.

template<class T>

Array<T>* casacore::LatticeIterInterface< T >::itsCurPtr

protected

Polymorphic pointer to the data in itsCursor.

Definition at line 254 of file LatticeIterInterface.h.

template<class T>

Array<T> casacore::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 258 of file LatticeIterInterface.h.