A readonly iterator for masked Lattices. More...

#include <MaskedLatticeIterator.h>

Inheritance diagram for casacore::RO_MaskedLatticeIterator< T >:

Public Member Functions
	RO_MaskedLatticeIterator ()
	The default constructor creates an empty object which is practically unusable. More...

	RO_MaskedLatticeIterator (const MaskedLattice< T > &data, Bool useRef=True)
	Construct the Iterator with the supplied data. More...

	RO_MaskedLatticeIterator (const MaskedLattice< T > &data, const LatticeNavigator &method, Bool useRef=True)
	Construct the Iterator with the supplied data, and iteration strategy. More...

	RO_MaskedLatticeIterator (const MaskedLattice< T > &data, const IPosition &cursorShape, Bool useRef=True)
	Construct the Iterator with the supplied data. More...

	RO_MaskedLatticeIterator (const RO_MaskedLatticeIterator< T > &other)
	The copy constructor uses reference semantics (ie. More...

	~RO_MaskedLatticeIterator ()
	Destructor (cleans up dangling references and releases memory) More...

RO_MaskedLatticeIterator< T > &	operator= (const RO_MaskedLatticeIterator< T > &)
	Assignment uses reference semantics (ie. More...

RO_MaskedLatticeIterator< T >	copy () const
	Make a copy of the iterator object. More...

MaskedLattice< T > &	lattice () const
	Return the underlying MaskedLattice object. More...

Bool	isMasked () const
	Is the underlying MaskedLattice really masked? More...

Bool	getMask (COWPtr< Array< Bool > > &, Bool removeDegenerateAxes=False) const
	Get the mask for the current position. More...

Bool	getMask (Array< Bool > &, Bool removeDegenerateAxes=False) const

Array< Bool >	getMask (Bool removeDegenerateAxes=False) const

Public Member Functions inherited from casacore::RO_LatticeIterator< T >
	RO_LatticeIterator ()
	The default constructor creates an empty object which is practically unusable. More...

	RO_LatticeIterator (const Lattice< T > &data, Bool useRef=True)
	Construct the Iterator with the supplied data. More...

	RO_LatticeIterator (const Lattice< T > &data, const LatticeNavigator &method, Bool useRef=True)
	Construct the Iterator with the supplied data, and iteration strategy. More...

	RO_LatticeIterator (const Lattice< T > &data, const IPosition &cursorShape, Bool useRef=True)
	Construct the Iterator with the supplied data. More...

	RO_LatticeIterator (const RO_LatticeIterator< T > &other)
	The copy constructor uses reference semantics (ie. More...

	~RO_LatticeIterator ()
	Destructor (cleans up dangling references and releases memory) More...

RO_LatticeIterator< T > &	operator= (const RO_LatticeIterator< T > &other)
	Assignment uses reference semantics (ie. More...

RO_LatticeIterator< T >	copy () const
	Make a copy of the iterator object. More...

Bool	isNull () const
	Is the iterator object empty? More...

Lattice< T > &	lattice () const
	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 a value of "True" if an attempt has been made to move the cursor beyond the end of the Lattice. 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...

const Vector< T > &	vectorCursor () const
	Functions which returns a window to the data in the Lattice. More...

const Matrix< T > &	matrixCursor () const

const Cube< T > &	cubeCursor () const

const Array< T > &	cursor () const

Bool	ok () const
	Function which checks the internals of the class for consistency. More...

Private Member Functions
	RO_MaskedLatticeIterator (const RO_LatticeIterator< T > &, const RO_MaskedLatticeIterator< T > &)
	Construct from a LatticeIterator (for copy function). More...

void	fillPtr (const MaskedLattice< T > &mlattice)
	Fill the pointer with a pointer to the masked lattice. More...

Private Attributes
CountedPtr< MaskedLattice< T > >	itsMaskLattPtr

Additional Inherited Members
Protected Attributes inherited from casacore::RO_LatticeIterator< T >
CountedPtr < LatticeIterInterface< T > >	itsIterPtr
	The pointer to the Iterator. More...

Detailed Description

template<class T>
class casacore::RO_MaskedLatticeIterator< T >

A readonly iterator for masked Lattices.

Intended use:

Public interface

Review Status

Test programs:: tMaskedLatticeIterator

Prerequisite

Etymology

The leading "RO" is shorthand for "readonly", which indicates that an RO_MaskedLatticeIterator is used for traversing a masked lattice, examining and possibly extracting its contents, but not for modifying it.

Synopsis

This class provides a convenient way to traverse any class derived from MaskedLattice. It is derived from class RO_LatticeIterator, so it provides the same iterator capabilities. On top of that it offers the function getMask to get the contents of the mask at the current iterator position.

In principle, iteration through a MaskedLattice can be done as:

void someFunc (const MaskedLattice<Float>& lattice)
{
RO_LatticeIterator<Float> iter(lattice);
Array<Bool> mask;
while (! iter.atEnd()) {
const Array<Float>& array = iter.cursor();
lattice.getMaskSlice (mask, iter.position(), array.shape());
iter++;
}
}

Using a MaskedLatticeIterator makes getting the mask slightly more convenient.

void someFunc (const MaskedLattice<Float>& lattice)
{
RO_MaskedLatticeIterator<Float> iter(lattice);
Array<Bool> mask;
while (! iter.atEnd()) {
const Array<Float>& array = iter.cursor();
iter.getMask (mask);
iter++;
}
}

However, the most important reason to use MaskedLatticeIterator is performance. If the underlying lattice is a LatticeExpr object, the expression will be evaluated twice if a LatticeIterator object is used. The reason is that the lattice in the LatticeIterator is a different object from the lattice object used to get the mask. Hence, the optimization put in LatticeExpr is not used. When using a MaskedLatticeIterator the same lattice object is used to get data and mask.

Motivation

The performance gain for LatticeExpr was the most important reason to develop this class.

Definition at line 115 of file MaskedLatticeIterator.h.

Constructor & Destructor Documentation

template<class T>

casacore::RO_MaskedLatticeIterator< T >::RO_MaskedLatticeIterator ( )

The default constructor creates an empty object which is practically unusable.

It can only be used as the source or target of an assignment. It can also be used as the source for the copy constructor and the copy function. Other functions do not check if the object is empty and will usually give a segmentation fault. The function isNull() can be used to test if the object is empty.

template<class T>

casacore::RO_MaskedLatticeIterator< T >::RO_MaskedLatticeIterator	(	const MaskedLattice< T > &	data,
		Bool	useRef = `True`
	)

explicit

Construct the Iterator with the supplied data.

It uses a TileStepper as the default iteration strategy. useRef=True means that if possible the cursor arrays returned reference the data in the underlying lattice. This is only possible for ArrayLattice objects (or e.g. a SubLattice using it).

template<class T>

casacore::RO_MaskedLatticeIterator< T >::RO_MaskedLatticeIterator	(	const MaskedLattice< T > &	data,
		const LatticeNavigator &	method,
		Bool	useRef = `True`
	)

Construct the Iterator with the supplied data, and iteration strategy.

template<class T>

casacore::RO_MaskedLatticeIterator< T >::RO_MaskedLatticeIterator	(	const MaskedLattice< T > &	data,
		const IPosition &	cursorShape,
		Bool	useRef = `True`
	)

Construct the Iterator with the supplied data.

It uses a LatticeStepper with the supplied cursor shape as the iteration strategy.

template<class T>

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

The copy constructor uses reference semantics (ie.

NO real copy is made). The function copy can be used to make a true copy.

template<class T>

casacore::RO_MaskedLatticeIterator< T >::~RO_MaskedLatticeIterator ( )

Destructor (cleans up dangling references and releases memory)

template<class T>

casacore::RO_MaskedLatticeIterator< T >::RO_MaskedLatticeIterator	(	const RO_LatticeIterator< T > &	,
		const RO_MaskedLatticeIterator< T > &
	)

private

Construct from a LatticeIterator (for copy function).

Member Function Documentation

template<class T>

RO_MaskedLatticeIterator<T> casacore::RO_MaskedLatticeIterator< T >::copy ( ) const

Make a copy of the iterator object.

This means that an independent navigator object is created to be able to iterate independently through the same MaskedLattice. The position in the copied navigator is the same as the original. The reset function has to be used to start at the beginning.
Note that if the MaskedLattice uses a cache (e.g. PagedArray), the cache is shared by the iterators.

template<class T>

void casacore::RO_MaskedLatticeIterator< T >::fillPtr ( const MaskedLattice< T > & mlattice )

private

Fill the pointer with a pointer to the masked lattice.

This pointer is a casted copy of the lattice pointer in the base class. In this way they share the same MaskedLattice object, which is needed for optimal performance of e.g. LatticeExpr. Otherwise getting data from the lattice and from the mask would result in 2 evaluations of the expression. However, the lattice can be a PagedArray (for example, for PagedImage). In that case a clone of the original MaskedLattice is used.

template<class T>

Bool casacore::RO_MaskedLatticeIterator< T >::getMask	(	COWPtr< Array< Bool > > &	,
		Bool	removeDegenerateAxes = `False`
	)		const

Get the mask for the current position.

It returns the same flag as MaskedLattice::getMaskSlice.

template<class T>

Bool casacore::RO_MaskedLatticeIterator< T >::getMask	(	Array< Bool > &	,
		Bool	removeDegenerateAxes = `False`
	)		const

template<class T>

Array<Bool> casacore::RO_MaskedLatticeIterator< T >::getMask ( Bool removeDegenerateAxes = False ) const

template<class T>

Bool casacore::RO_MaskedLatticeIterator< T >::isMasked ( ) const

inline

Is the underlying MaskedLattice really masked?

Definition at line 179 of file MaskedLatticeIterator.h.

References casacore::RO_MaskedLatticeIterator< T >::itsMaskLattPtr.

template<class T>

MaskedLattice<T>& casacore::RO_MaskedLatticeIterator< T >::lattice ( ) const

inline

Return the underlying MaskedLattice object.

Definition at line 175 of file MaskedLatticeIterator.h.

template<class T>

RO_MaskedLatticeIterator<T>& casacore::RO_MaskedLatticeIterator< T >::operator= ( const RO_MaskedLatticeIterator< T > & )

Assignment uses reference semantics (ie.

NO real copy is made). The function copy can be used to make a true copy.

Member Data Documentation

template<class T>

CountedPtr<MaskedLattice<T> > casacore::RO_MaskedLatticeIterator< T >::itsMaskLattPtr

private

Definition at line 206 of file MaskedLatticeIterator.h.

Referenced by casacore::RO_MaskedLatticeIterator< T >::isMasked().

The documentation for this class was generated from the following file:

lattices/Lattices/MaskedLatticeIterator.h

Public Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

template<class T> class casacore::RO_MaskedLatticeIterator< T >

Intended use:

Review Status

Prerequisite

Etymology

Synopsis

Motivation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

template<class T>
class casacore::RO_MaskedLatticeIterator< T >