casacore
LatticeIterInterface.h
Go to the documentation of this file.
1//# LatticeIterInterface.h: A base class for Lattice iterators
2//# Copyright (C) 1994,1995,1996,1997,1998,1999,2003
3//# Associated Universities, Inc. Washington DC, USA.
4//#
5//# This library is free software; you can redistribute it and/or modify it
6//# under the terms of the GNU Library General Public License as published by
7//# the Free Software Foundation; either version 2 of the License, or (at your
8//# option) any later version.
9//#
10//# This library is distributed in the hope that it will be useful, but WITHOUT
11//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12//# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13//# License for more details.
14//#
15//# You should have received a copy of the GNU Library General Public License
16//# along with this library; if not, write to the Free Software Foundation,
17//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18//#
19//# Correspondence concerning AIPS++ should be addressed as follows:
20//# Internet email: aips2-request@nrao.edu.
21//# Postal address: AIPS++ Project Office
22//# National Radio Astronomy Observatory
23//# 520 Edgemont Road
24//# Charlottesville, VA 22903-2475 USA
25//#
26//# $Id$
27
28#ifndef LATTICES_LATTICEITERINTERFACE_H
29#define LATTICES_LATTICEITERINTERFACE_H
30
31
32//# Includes
33#include <casacore/casa/aips.h>
34#include <casacore/casa/Arrays/IPosition.h>
35#include <casacore/casa/Arrays/Array.h>
36#include <casacore/lattices/Lattices/LatticeNavigator.h>
37
38namespace casacore { //# NAMESPACE CASACORE - BEGIN
39
40//# Forward Declarations
41template <class T> class Lattice;
42template <class T> class LatticeIterator;
43template <class T> class RO_LatticeIterator;
44
45
46// <summary>
47// A base class for Lattice iterators
48// </summary>
49
50// <use visibility=local>
51
52// <reviewed reviewer="Peter Barnes" date="1999/10/30" tests="tLatticeIterator.cc" demos="">
53// </reviewed>
54
55// <prerequisite>
56// <li> letter/envelope schemes - see Coplien, "Advanced C++", ch 5.5
57// <li> <linkto class="Lattice">Lattice</linkto>
58// <li> <linkto class="LatticeIterator">LatticeIterator</linkto>
59// </prerequisite>
60
61// <etymology>
62// The LatticeIterInterface class name reflects its role as the abstract
63// base class for concrete read-write LatticeIterators
64// </etymology>
65
66// <synopsis>
67// This class is only for authors of Lattice letters for the LatticeIterator
68// envelope. General users should see LatticeIterator.
69//
70// The LatticeIterInterface class defines an abstract base for the standard
71// methods of iteration required by Lattices. Declaring an Iterator that is
72// derived from this class forces it to meet the virtual requirements.
73//
74// The author of a Lattice derived class should consider the following:
75// <ul>
76// <li> The LatticeStepper class has strong effects on how the cursor is
77// filled. A non-integral shape of the cursor may allow a step of
78// iteration to be only partially "touching" the Lattice. We have dubbed
79// this "hangover."
80// <li> If the cursor has "hangover" it should be filled with a value that
81// indicates the cursor is in undefined space.
82// <li> The cursor cannot be a reference to a part of the Lattice since
83// hangover would imply a reference to undefined memory. To enclose the
84// Lattice with a zero valued hangover buffer would be inefficient. The
85// method thus forced upon the programmer is to "update" the cursor with
86// Lattice values after each move or iteration and to "write" the possibly
87// changed cursor values back into the Lattice before each iteration. An
88// algorithm which does the cursor update/write actions (and is independent
89// of Lattice dimensionality) may be copied from ArrLatticeIter::cursorUpdate()
90// and ArrLatticeIter::cursorWrite(), respectively.
91// <li> The majority of the code in a new letter for LatticeIterator may be
92// cut and pasted from other implementations of letters. See ArrLatticeIter
93// or PagedArrIter.
94// </ul>
95// </synopsis>
96
97// <example>
98// For an example see <linkto class=LatticeIterator>LatticeIterator</linkto>.
99// </example>
100
101// <motivation>
102// The is class provides a tidy base for letter/envelope techniques of
103// iteration.
104// </motivation>
105
106// <todo asof="1997/01/12">
107// <li> IPositions are returned by value. This a reflection of the
108// LatticeNavigator base class' inability to predict the
109// availibility of data members for references.
110// </todo>
111
112
113template <class T> class LatticeIterInterface
114{
115friend class Lattice<T>;
116friend class LatticeIterator<T>;
117friend class RO_LatticeIterator<T>;
118
119public:
120 // Construct with the given navigator.
122 const LatticeNavigator& navigator,
123 Bool useRef);
124
125 // A virtual destructor. A virtual is needed to ensure that derived
126 // classes declared as pointers to a LatticeIterInterface will scope their
127 // destructor to the derived class destructor.
129
130protected:
131 // Default constructor (for derived classes).
133
134 // Copy constructor (copy semantics).
136
137 // Assignment (copy semantics).
139
140 // Clone the object.
142
143 // Return the underlying lattice.
145 { return *itsLattPtr; }
146
147 // Increment operator - increment the cursor to the next position. The
148 // implementation of the prefix operator calls the postfix one.
149 // <group>
152 // </group>
153
154 // Decrement operator - decrement the cursor to the previous position. The
155 // implementation of the prefix operator calls the postfix one.
156 // <group>
159 // </group>
160
161 // Function which resets the cursor to the beginning of the Lattice and
162 // resets the number of steps taken to zero.
163 void reset();
164
165 // Function which returns a value of "True" if the cursor is at the
166 // beginning of the Lattice, otherwise, returns "False"
167 Bool atStart() const;
168
169 // Function which returns "True" if the cursor has been incremented to
170 // the end of the lattice, otherwise, returns "False"
171 Bool atEnd() const;
172
173 // Function to return the number of steps (increments or decrements) taken
174 // since construction (or since last reset). This is a running count of
175 // all cursor movement since doing N increments followed by N decrements
176 // does not necessarily put the cursor back at the origin of the Lattice.
177 uInt nsteps() const;
178
179 // Function which returns the current position of the beginning of the
180 // cursor within the Lattice. The returned IPosition will have the same
181 // number of axes as the underlying Lattice.
182 IPosition position() const;
183
184 // Function which returns the current position of the end of the
185 // cursor. The returned IPosition will have the same number of axes as the
186 // underlying Lattice.
187 IPosition endPosition() const;
188
189 // Function which returns the shape of the Lattice being iterated through.
190 // The returned IPosition will always have the same number of axes as the
191 // underlying Lattice.
192 IPosition latticeShape() const;
193
194 // Function which returns the shape of the cursor which is iterating
195 // through the Lattice. The cursor will always have as many dimensions as
196 // the Lattice.
197 IPosition cursorShape() const;
198
199 // Functions which returns a window to the data in the Lattice. These are
200 // used to read the data within the Lattice. Use the function
201 // that is appropriate to the current cursor dimension, AFTER REMOVING
202 // DEGENERATE AXES, or use the <src>cursor</src> function which works with
203 // any number of dimensions in the cursor. A call of the function whose
204 // return value is inappropriate with respect to the current cursor
205 // dimension will throw an exception (AipsError).
206 // <br>The <src>doRead</src> flag indicates if the data need to be read or
207 // if only a cursor with the correct shape has to be returned.
208 // <br>The <src>autoRewrite</src> flag indicates if the data has to be
209 // rewritten when the iterator state changes (e.g. moved, destructed).
210 // <group>
211 virtual Vector<T>& vectorCursor (Bool doRead, Bool autoRewrite);
212 virtual Matrix<T>& matrixCursor (Bool doRead, Bool autoRewrite);
213 virtual Cube<T>& cubeCursor (Bool doRead, Bool autoRewrite);
214 virtual Array<T>& cursor (Bool doRead, Bool autoRewrite);
215 //</group>
216
217 // Function which checks the internals of the class for consistency.
218 // Returns True if everything is fine otherwise returns False. The default
219 // implementation of this function always returns True.
220 Bool ok() const;
221
222protected:
223 // Do the actual read of the data.
224 virtual void readData (Bool doRead);
225
226 // Rewrite the cursor data and clear the rewrite flag.
227 virtual void rewriteData();
228
229 // Update the cursor for the next chunk of data (resize if needed).
230 virtual void cursorUpdate();
231
232 // Allocate the internal buffer.
234
235 // Allocate the nondegenerate array with the correct type.
237
238 // Synchronise the storage of itsCurPtr with itsCursor.
240
241 // Copy the base data of the other object.
243
244
245 // Pointer to the method of Lattice transversal
247 // Pointer to the Lattice
249 // A buffer to hold the data. Usually itsCursor shares the data
250 // with this buffer, but for an ArrayLattice itsCursor might reference
251 // the lattice directly instead of making a copy in the buffer.
253 // Polymorphic pointer to the data in itsCursor.
255 // An Array which references the same data as the itsCurPtr, but has all
256 // the degenerate axes. This is an optimization to avoid the overhead of
257 // having to add the degenerate axes for each iteration.
259 // Keep a reference to the data (if possible).
261 // Is the cursor a reference to the lattice?
263 // Have the data been read after a cursor update? (False=not read)
265 // Rewrite the cursor data before moving or destructing?
267 // The axes forming the cursor.
269};
270
271
272
273template <class T>
275 return operator++ (0);
276}
277
278template <class T>
280 return operator-- (0);
281}
282
283template<class T>
285{
286 return itsNavPtr->atStart();
287}
288
289template<class T>
291{
292 return itsNavPtr->atEnd();
293}
294
295template<class T>
297{
298 return itsNavPtr->nsteps();
299}
300
301template<class T>
303{
304 return itsNavPtr->position();
305}
306
307template<class T>
309{
310 return itsNavPtr->endPosition();
311}
312
313template<class T>
315{
316 return itsNavPtr->latticeShape();
317}
318
319template<class T>
321{
322 return itsNavPtr->cursorShape();
323}
324
325//# Declare extern templates for often used types.
326 extern template class LatticeIterInterface<Float>;
327
328
329} //# NAMESPACE CASACORE - END
330
331#ifndef CASACORE_NO_AUTO_TEMPLATES
332#include <casacore/lattices/Lattices/LatticeIterInterface.tcc>
333#endif //# CASACORE_NO_AUTO_TEMPLATES
334#endif
Bool atEnd() const
Function which returns "True" if the cursor has been incremented to the end of the lattice,...
LatticeIterInterface()
Default constructor (for derived classes).
virtual LatticeIterInterface< T > * clone() const
Clone the object.
Bool itsRewrite
Rewrite the cursor data before moving or destructing?
void setCurPtr2Cursor()
Synchronise the storage of itsCurPtr with itsCursor.
uInt nsteps() const
Function to return the number of steps (increments or decrements) taken since construction (or since ...
IPosition endPosition() const
Function which returns the current position of the end of the cursor.
LatticeIterInterface & operator=(const LatticeIterInterface< T > &other)
Assignment (copy semantics).
LatticeNavigator * itsNavPtr
Pointer to the method of Lattice transversal.
virtual void cursorUpdate()
Update the cursor for the next chunk of data (resize if needed).
Bool itsIsRef
Is the cursor a reference to the lattice?
Array< T > itsCursor
An Array which references the same data as the itsCurPtr, but has all the degenerate axes.
void allocateCurPtr()
Allocate the nondegenerate array with the correct type.
void allocateBuffer()
Allocate the internal buffer.
IPosition latticeShape() const
Function which returns the shape of the Lattice being iterated through.
Lattice< T > & lattice()
Return the underlying lattice.
virtual Matrix< T > & matrixCursor(Bool doRead, Bool autoRewrite)
virtual void rewriteData()
Rewrite the cursor data and clear the rewrite flag.
Bool operator--()
Decrement operator - decrement the cursor to the previous position.
Bool atStart() const
Function which returns a value of "True" if the cursor is at the beginning of the Lattice,...
virtual Vector< T > & vectorCursor(Bool doRead, Bool autoRewrite)
Functions which returns a window to the data in the Lattice.
Bool itsUseRef
Keep a reference to the data (if possible).
Bool itsHaveRead
Have the data been read after a cursor update? (False=not read)
Bool operator++()
Increment operator - increment the cursor to the next position.
LatticeIterInterface(const LatticeIterInterface< T > &other)
Copy constructor (copy semantics).
virtual Array< T > & cursor(Bool doRead, Bool autoRewrite)
void reset()
Function which resets the cursor to the beginning of the Lattice and resets the number of steps taken...
Array< T > itsBuffer
A buffer to hold the data.
Bool ok() const
Function which checks the internals of the class for consistency.
Lattice< T > * itsLattPtr
Pointer to the Lattice.
Array< T > * itsCurPtr
Polymorphic pointer to the data in itsCursor.
LatticeIterInterface(const Lattice< T > &lattice, const LatticeNavigator &navigator, Bool useRef)
Construct with the given navigator.
IPosition cursorShape() const
Function which returns the shape of the cursor which is iterating through the Lattice.
void copyBase(const LatticeIterInterface< T > &other)
Copy the base data of the other object.
IPosition itsCursorAxes
The axes forming the cursor.
IPosition position() const
Function which returns the current position of the beginning of the cursor within the Lattice.
virtual Cube< T > & cubeCursor(Bool doRead, Bool autoRewrite)
virtual ~LatticeIterInterface()
A virtual destructor.
virtual void readData(Bool doRead)
Do the actual read of the data.
A read/write lattice iterator.
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:51
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42