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