A readonly iterator for masked Lattices. More...

#include <MaskedLatticeIterator.h>

Inheritance diagram for casa::RO_MaskedLatticeIterator< T >:

Public Member Functions
	RO_MaskedLatticeIterator ()
	The default constructor creates an empty object which is practically unusable.
	RO_MaskedLatticeIterator (const MaskedLattice< T > &data, Bool useRef=True)
	Construct the Iterator with the supplied data.
	RO_MaskedLatticeIterator (const MaskedLattice< T > &data, const LatticeNavigator &method, Bool useRef=True)
	Construct the Iterator with the supplied data, and iteration strategy.
	RO_MaskedLatticeIterator (const MaskedLattice< T > &data, const IPosition &cursorShape, Bool useRef=True)
	Construct the Iterator with the supplied data.
	RO_MaskedLatticeIterator (const RO_MaskedLatticeIterator< T > &other)
	The copy constructor uses reference semantics (ie.
	~RO_MaskedLatticeIterator ()
	Destructor (cleans up dangling references and releases memory)
RO_MaskedLatticeIterator< T > &	operator= (const RO_MaskedLatticeIterator< T > &)
	Assignment uses reference semantics (ie.
RO_MaskedLatticeIterator< T >	copy () const
	Make a copy of the iterator object.
MaskedLattice< T > &	lattice () const
	Return the underlying MaskedLattice object.
Bool	isMasked () const
	Is the underlying MaskedLattice really masked?
Bool	getMask (COWPtr< Array< Bool > > &, Bool removeDegenerateAxes=False) const
	Get the mask for the current position.
Bool	getMask (Array< Bool > &, Bool removeDegenerateAxes=False) const
Array< Bool >	getMask (Bool removeDegenerateAxes=False) const
Private Member Functions
	RO_MaskedLatticeIterator (const RO_LatticeIterator< T > &, const RO_MaskedLatticeIterator< T > &)

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

Detailed Description

template<class T>
class casa::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>

casa::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>

casa::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>

casa::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>

casa::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>

casa::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>

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

Destructor (cleans up dangling references and releases memory)

template<class T>

casa::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> casa::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.

Reimplemented from casa::RO_LatticeIterator< T >.

template<class T>

void casa::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 casa::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 casa::RO_MaskedLatticeIterator< T >::getMask	(	Array< Bool > &	,
		Bool	removeDegenerateAxes = `False`
	)		const

template<class T>

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

template<class T>

Bool casa::RO_MaskedLatticeIterator< T >::isMasked ( ) const [inline]

Is the underlying MaskedLattice really masked?

Definition at line 179 of file MaskedLatticeIterator.h.

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

template<class T>

MaskedLattice<T>& casa::RO_MaskedLatticeIterator< T >::lattice ( ) const [inline]

Return the underlying MaskedLattice object.

Reimplemented from casa::RO_LatticeIterator< T >.

Definition at line 175 of file MaskedLatticeIterator.h.

template<class T>

RO_MaskedLatticeIterator<T>& casa::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> > casa::RO_MaskedLatticeIterator< T >::itsMaskLattPtr [private]

Definition at line 206 of file MaskedLatticeIterator.h.

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

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

casacore/lattices/Lattices/MaskedLatticeIterator.h

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

template<class T> class casa::RO_MaskedLatticeIterator< T >

Intended use:

Review Status

Prerequisite

Etymology

Synopsis

Motivation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

template<class T>
class casa::RO_MaskedLatticeIterator< T >