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 Lattice;
42 template <class T> class LatticeIterator;
43 template <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 
113 template <class T> class LatticeIterInterface
114 {
115 friend class Lattice<T>;
116 friend class LatticeIterator<T>;
117 friend class RO_LatticeIterator<T>;
118 
119 public:
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 
130 protected:
131  // Default constructor (for derived classes).
133 
134  // Copy constructor (copy semantics).
136 
137  // Assignment (copy semantics).
139 
140  // Clone the object.
141  virtual LatticeIterInterface<T>* clone() const;
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>
150  Bool operator++();
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>
157  Bool operator--();
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 
222 protected:
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.
242  void copyBase (const LatticeIterInterface<T>& other);
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 
273 template <class T>
275  return operator++ (0);
276 }
277 
278 template <class T>
280  return operator-- (0);
281 }
282 
283 template<class T>
285 {
286  return itsNavPtr->atStart();
287 }
288 
289 template<class T>
291 {
292  return itsNavPtr->atEnd();
293 }
294 
295 template<class T>
297 {
298  return itsNavPtr->nsteps();
299 }
300 
301 template<class T>
303 {
304  return itsNavPtr->position();
305 }
306 
307 template<class T>
309 {
310  return itsNavPtr->endPosition();
311 }
312 
313 template<class T>
315 {
316  return itsNavPtr->latticeShape();
317 }
318 
319 template<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,...
virtual Matrix< T > & matrixCursor(Bool doRead, Bool autoRewrite)
LatticeIterInterface()
Default constructor (for derived classes).
virtual Vector< T > & vectorCursor(Bool doRead, Bool autoRewrite)
Functions which returns a window to the data in the Lattice.
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.
virtual LatticeIterInterface< T > * clone() const
Clone the object.
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.
virtual Array< T > & cursor(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,...
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 Cube< T > & cubeCursor(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.
LatticeIterInterface & operator=(const LatticeIterInterface< T > &other)
Assignment (copy semantics).
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 ~LatticeIterInterface()
A virtual destructor.
virtual void readData(Bool doRead)
Do the actual read of the data.
Lattice< T > & lattice()
Return the underlying lattice.
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