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
34namespace casacore { //# NAMESPACE CASACORE - BEGIN
35
36//# Forward Declarations
37class 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{
88public:
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.
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
171protected:
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
178private:
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.
192inline 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)
const IPosition & pos() const
Return the position of the cursor.
Definition: ArrayPosIter.h:139
ArrayPositionIterator(const IPosition &shape, const IPosition &axes, bool axesAreCursor=true)
Step through an array using the given axes.
const IPosition & iterAxes() const
Return the iteration axes.
Definition: ArrayPosIter.h:161
IPosition endPos() const
Return the end position of the cursor.
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
const IPosition & cursorAxes() const
Return the cursor axes.
Definition: ArrayPosIter.h:164
void setup(size_t byDim)
Setup the object for the constructor.
virtual ArrayBase & getArray()
Get the array in the cursor.
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