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