casacore
ArrayPosIter.h
Go to the documentation of this file.
1 //# ArrayPosIter.h: Iterate an IPosition through the shape of an Array
2 //# Copyright (C) 1993,1994,1995,1998,1999,2004
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 CASA_ARRAYPOSITER_H
29 #define CASA_ARRAYPOSITER_H
30 
31 #include <casacore/casa/aips.h>
32 //# Change the following to a forward declare?
33 #include <casacore/casa/Arrays/IPosition.h>
34 
35 namespace casacore { //# NAMESPACE CASACORE - BEGIN
36 
37 //# Forward Declarations
38 class ArrayBase;
39 
40 
41 // <summary> Iterate an IPosition through the shape of an Array </summary>
42 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="" demos="">
43 // </reviewed>
44 
45 // <synopsis>
46 // ArrayPositionIterator manipulates an IPosition "cursor" through some
47 // volume defined by an origin and shape. This position can in turn be
48 // used to index into, or otherwise define a position in, an Array. Normally
49 // users won't use this class directly, rather they will use an ArrayIterator,
50 // VectorIterator or MatrixIterator object, which in turn uses this class.
51 // ArrayPositionIterator is also used in the implementation of Array.
52 //
53 // <srcblock>
54 // template<class T> void verySlowArrayCopy(Array<T> &to, const Array<T> &from)
55 // {
56 // if (! to.conform(from)) {
57 // // throw some error
58 // }
59 // ArrayPositionIterator toiter(to.shape(), to.origin(),0);
60 // ArrayPositionIterator fromiter(from.shape(), from.origin(),0);
61 // // If to.origin() == from.origin() we only need one iterator
62 // // or we could offset positions by the difference in origins.
63 // // The "0" means we are stepping by scalars.
64 // while (! toiter.pastEnd()) { // we know arrays conform
65 // to(toiter.pos()) = fromiter(fromiter.pos());
66 // toiter.next(); fromiter.next();
67 // }
68 // }
69 // </srcblock>
70 //
71 // Iteration can be done by any combination of axes, but it can only be
72 // done for full axes.
73 // <br>The iteration step always "fills up" its dimensionality.
74 // E.g., if we are stepping through a cube by matrices, the matrix completely
75 // fills up the plane.
76 // Class <linkto class=ArrayLattice>ArrayLattice</linkto> in the lattices
77 // package can be used to iterate with partial volumes.
78 //
79 // <p>
80 // ArrayPositionIterator also serves as the base class of ArrayIterator.
81 // Function <src>makeIterator</src> in class ArrayBase can be used to make an
82 // ArrayIterator without having to know the template type. Function
83 // <src>getArray</src> in this class can be used to obtain the current
84 // contents of the cursor as an ArrayBase object.
85 // </synopsis>
86 
88 {
89 public:
90  // Define the shape and origin of the volume the cursor will step
91  // through. Also define the dimensionality of the step. byDim==0 implies
92  // we are stepping by scalars (i.e. every element), byDim==1 implies that
93  // we are stepping by vector, ==2 by matrices, and so on.
94  // If uses the first byDim axes as the cursor volume and it steps
95  // through the remaining axes.
96  // <group>
98  uInt byDim);
99  ArrayPositionIterator(const IPosition &shape,
100  uInt byDim);
101  // </group>
102 
103  // Step through an array using the given axes.
104  // The axes can be given in two ways:
105  // <ol>
106  // <li>axesAreCursor=True means that the axes form the cursor axes.
107  // The remaining axes will form the iteration axes.
108  // This is the default.
109  // <li>axesAreCursor=False means the opposite.
110  // In this case the iteration axes can be given in any order.
111  // </ol>
112  // E.g. when using iteration axes 2,0 for an array with shape [5,3,7], each
113  // iteration step returns a cursor (containing the data of axis 1).
114  // During the iteration axis 2 will vary most rapidly (as it was
115  // given first).
116  // <br>E.g. for a shape of [3,4,5,6] and cursor axes [2,0], the cursor size
117  // is [3,5] (axes 0 and 2), while the iteration is done over axes 1 and 3
118  // (1 the fastest varying one).
119  ArrayPositionIterator(const IPosition &shape,
120  const IPosition &axes,
121  Bool axesAreCursor=True);
122 
124 
125  // Reset the cursor to the beginning of the volume.
126  // <group>
127  virtual void reset();
128  void origin()
129  { reset(); }
130  // </group>
131 
132  // Returns true of the cursor is at the origin.
133  Bool atStart() const;
134 
135  // Returns true if the cursor has moved past the end of its volume.
136  Bool pastEnd() const;
137 
138  // Return the position of the cursor.
139  // This include all axes
140  const IPosition &pos() const {return Cursor;}
141 
142  // Return the end position of the cursor.
143  IPosition endPos() const;
144 
145  // Advance the cursor to its next position.
146  virtual void next();
147 
148  // Set the cursor to the given position.
149  // The position can only contain the iteration axes or it can be the full
150  // position.
151  // <br>In the first case the position must to be given in the order
152  // of the iteration axes as given in the constructor.
153  // In the latter case the position must be given in natural order
154  // (as given by function <src>pos</src> and only the cursor axes are taken
155  // into account.
156  virtual void set (const IPosition& cursorPos);
157 
158  // What is the dimensionality of the volume we are iterating through?
159  uInt ndim() const;
160 
161  // Return the iteration axes.
162  const IPosition &iterAxes() const {return iterationAxes;}
163 
164  // Return the cursor axes.
165  const IPosition &cursorAxes() const {return cursAxes;}
166 
167  // Get the array in the cursor.
168  // This is only implemented in the derived ArrayIterator class.
169  // By default it throws an exception.
170  virtual ArrayBase& getArray();
171 
172 protected:
173  // Advance cursor to its next position and tell which dimension stepped.
174  uInt nextStep();
175  // What is the dimensionality of the "step" the cursor takes, i.e.
176  // 0 for scalars, 1 for vector, ....
177  uInt dimIter() const {return cursAxes.nelements();}
178 
179 private:
180  // Setup the object for the constructor.
181  // <group>
182  void setup(uInt byDim);
183  void setup(const IPosition &axes, Bool axesAreCursor);
184  // </group>
185 
186  //# We should probably have mf's for getting at Start,Shape and End.
190 };
191 
192 // Dimensionality of the array we are iterating through.
194 {
195  return Start.nelements();
196 }
197 
198 // We are at the "end" if we cannot advance any more.
200 {
201  return atOrBeyondEnd;
202 }
203 
204 
205 } //# NAMESPACE CASACORE - END
206 
207 #endif
A Vector of integers, for indexing into Array<T> objects.
Definition: IPosition.h:119
Non-templated base class for templated Array class.
Definition: ArrayBase.h:74
uInt nextStep()
Advance cursor to its next position and tell which dimension stepped.
virtual void next()
Advance the cursor to its next position.
const IPosition & cursorAxes() const
Return the cursor axes.
Definition: ArrayPosIter.h:165
IPosition endPos() const
Return the end position of the cursor.
ArrayPositionIterator(const IPosition &shape, const IPosition &origin, uInt byDim)
Define the shape and origin of the volume the cursor will step through.
Bool pastEnd() const
Returns true if the cursor has moved past the end of its volume.
Definition: ArrayPosIter.h:199
uInt nelements() const
The number of elements in this IPosition.
Definition: IPosition.h:544
uInt dimIter() const
What is the dimensionality of the "step" the cursor takes, i.e.
Definition: ArrayPosIter.h:177
virtual void reset()
Reset the cursor to the beginning of the volume.
virtual ArrayBase & getArray()
Get the array in the cursor.
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
void setup(uInt byDim)
Setup the object for the constructor.
const IPosition & iterAxes() const
Return the iteration axes.
Definition: ArrayPosIter.h:162
const IPosition & pos() const
Return the position of the cursor.
Definition: ArrayPosIter.h:140
TableExprNode shape(const TableExprNode &array)
Function operating on any scalar or array resulting in a Double array containing the shape...
Definition: ExprNode.h:2163
Iterate an IPosition through the shape of an Array.
Definition: ArrayPosIter.h:87
Bool atStart() const
Returns true of the cursor is at the origin.
uInt ndim() const
What is the dimensionality of the volume we are iterating through?
Definition: ArrayPosIter.h:193
const Bool True
Definition: aipstype.h:43
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:51