casacore
ArrayBase.h
Go to the documentation of this file.
1 //# ArrayBase.h: Non-templated base class for templated Array class
2 //# Copyright (C) 1993,1994,1995,1996,1997,1998,1999,2000,2001,2002,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: ArrayBase.h 21521 2014-12-10 08:06:42Z gervandiepen $
27 
28 #ifndef CASA_ARRAYBASE_H
29 #define CASA_ARRAYBASE_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/casa/Arrays/IPosition.h>
35 #include <casacore/casa/Utilities/CountedPtr.h>
36 #include <casacore/casa/Containers/Allocator.h>
37 
38 namespace casacore { //# NAMESPACE CASACORE - BEGIN
39 
40 //# Forward declarations.
41 class ArrayPositionIterator;
42 class Slicer;
43 
44 
45 // <summary>
46 // A global enum used by some Array constructors.
47 // </summary>
48 // <synopsis>
49 // StorageInitPolicy is used in functions where an array is formed from
50 // a shape and an ordinary pointer. This enum should be in Array but that
51 // causes gcc to be unhappy.
52 // </synopsis>
54  // COPY is used when an internal copy of the storage is to be made.
55  // The array is NOT responsible for deleting the external storage.
57  // TAKE_OVER is used to indicate that the Array should just use the
58  // external storage (i.e., no copy is made). The Array class is now
59  // responsible for deleting the storage (hence it must have come from
60  // a call to new[]).
62  // Share means that the Array will just use the pointer (no copy), however
63  // the Array will NOT delete it upon destruction.
65 
66 
67 // <summary>
68 // Non-templated base class for templated Array class.
69 // </summary>
70 
71 // ArrayBase is only used to factor out common code from the templated
72 // Array class.
73 
74 class ArrayBase
75 {
76 public:
77  ArrayBase();
78 
79  // Create an array of the given shape, i.e. after construction
80  // array.ndim() == shape.nelements() and array.shape() == shape.
81  // The origin of the Array is zero.
82  explicit ArrayBase (const IPosition& shape);
83 
84  // Copy constructor.
85  ArrayBase (const ArrayBase& other);
86 
87  // Assignment.
89 
90  // Destructor.
91  virtual ~ArrayBase();
92 
93  // The dimensionality of this array.
94  uInt ndim() const
95  { return ndimen_p; }
96 
97  // How many elements does this array have? Product of all axis lengths.
98  // <group>
99  size_t nelements() const
100  { return nels_p; }
101  size_t size() const
102  { return nels_p; }
103  // </group>
104 
105  // Is the array empty (i.e. no elements)?
106  Bool empty() const
107  { return nels_p == 0; }
108 
109  // Are the array data contiguous?
110  // If they are not contiguous, <src>getStorage</src> (see below)
111  // needs to make a copy.
113  { return contiguous_p; }
114 
115  // Check to see if the Array is consistent. This is about the same thing
116  // as checking for invariants. If AIPS_DEBUG is defined, this is invoked
117  // after construction and on entry to most member functions.
118  virtual Bool ok() const;
119 
120  // The length of each axis.
121  const IPosition& shape() const
122  { return length_p; }
123 
124  // A convenience function: endPosition(i) = shape(i) - 1; i.e. this
125  // is the IPosition of the last element of the Array.
126  IPosition endPosition() const;
127 
128  // Return steps to be made if stepping one element in a dimension.
129  // This is the 'physical' step, thus it also works correctly for
130  // non-contiguous arrays. E.g. <src>data() + steps(0)</src> gives
131  // the second element of the first axis.
132  const IPosition& steps() const
133  { return steps_p; }
134 
135  // Array version for major change (used by ArrayIO).
136  // enum did not work properly with cfront 3.0.1), so replaced
137  // by a static inline function. Users won't normally use this.
139  {return 3;}
140 
141  // Make an empty array of the same type.
142  // <br>The default implementation in ArrayBase throws an exception.
143  virtual CountedPtr<ArrayBase> makeArray() const;
144 
145  // Resize the array and optionally copy the values.
146  // <br>The default implementation in ArrayBase throws an exception.
147  virtual void resize(const IPosition &newShape, Bool copyValues=False);
148 
149  // Resize the array and optionally copy the values.
150  // <br>The default implementation in ArrayBase throws an exception.
151  virtual void resize(const IPosition &newShape, Bool copyValues, ArrayInitPolicy policy);
152 
153  // Create an ArrayIterator object of the correct type.
154  // This is implemented in the derived Array classes.
155  // <br>The default implementation in ArrayBase throws an exception.
157 
158  // Get a reference to a section of an array.
159  // This is the same as Array<T>::operator(), but without having to know
160  // the exact template type.
161  // <br>The default implementation in ArrayBase throws an exception.
162  virtual CountedPtr<ArrayBase> getSection (const Slicer&) const;
163 
164  // Assign the source array to this array.
165  // If <src>checkType==True</src>, it is checked if the underlying template
166  // types match. Otherwise, it is only checked in debug mode (for performance).
167  // <br>The default implementation in ArrayBase throws an exception.
168  virtual void assignBase (const ArrayBase& source, Bool checkType=True);
169 
170  // The following functions behave the same as the corresponding getStorage
171  // functions in the derived templated Array class.
172  // They handle a pointer to a contiguous block of array data.
173  // If the array is not contiguous, a copy is used to make it contiguous.
174  // <group>
175  virtual void* getVStorage (Bool& deleteIt);
176  virtual const void* getVStorage (Bool& deleteIt) const;
177  virtual void putVStorage(void*& storage, Bool deleteAndCopy);
178  virtual void freeVStorage(const void*& storage, Bool deleteIt) const;
179  // <group>
180 
181 protected:
182  void baseCopy (const ArrayBase& that)
183  { operator= (that); }
184 
185  // Either reforms the array if size permits or resizes it to the new shape.
186  // Implementation of Array<T>::reformOrResize (slightly different signature).
187 
188  Bool reformOrResize (const IPosition & newShape,
189  Bool resizeIfNeeded,
190  uInt nReferences,
191  Int64 nElementsAllocated,
192  Bool copyDataIfNeeded,
193  uInt resizePercentage);
194 
195  // Determine if the storage of a subset is contiguous.
196  Bool isStorageContiguous() const;
197 
198  // Check if the shape of a vector is correct. If possible, adjust if not.
199  // It is possible if at most one axis has length > 1.
200  void checkVectorShape();
201 
202  // Check if the shape of a matrix is correct. Adjust it if smaller.
203  void checkMatrixShape();
204 
205  // Check if the shape of a cube is correct. Adjust it if smaller.
206  void checkCubeShape();
207 
208  // Reform the array to a shape with the same nr of elements. If nonStrict then
209  // caller assumes responsibility for not overrunning storage (avoid or use with extreme care).
210  void baseReform (ArrayBase& tmp, const IPosition& shape, Bool strict=True) const;
211 
212  // Remove the degenerate axes from the Array object.
213  // This is the implementation of the nonDegenerate functions.
214  // It has a different name to be able to make it virtual without having
215  // the "hide virtual function" message when compiling derived classes.
216  void baseNonDegenerate (const ArrayBase& other, const IPosition& ignoreAxes);
217 
218  // These member functions return an Array reference with the specified
219  // number of extra axes, all of length one, appended to the end of the
220  // Array. Note that the <src>reform</src> function can also be
221  // used to add extra axes.
222  void baseAddDegenerate (ArrayBase&, uInt numAxes);
223 
224  // Make a subset of an array.
225  // It checks if start,end,incr are within the array limits.
226  // It returns the offset of the subset in the array.
227  size_t makeSubset (ArrayBase& out,
228  const IPosition& b,
229  const IPosition& e,
230  const IPosition& i);
231 
232  // Are the shapes identical?
233  Bool conform2 (const ArrayBase& other) const
234  { return length_p.isEqual (other.length_p); }
235 
236  // Make the indexing step sizes.
237  void baseMakeSteps();
238 
239  // Throw expection if vector dimensionality is incorrect.
240  void throwNdimVector();
241 
242  // Helper function for templated Vector class.
243  // It returns if this and other are conformant.
244  Bool copyVectorHelper (const ArrayBase& other);
245 
246 public:
247  // Various helper functions.
248  // <group>
249  void validateConformance (const ArrayBase&) const;
250  void validateIndex (const IPosition&) const;
251  void validateIndex (uInt index) const;
252  void validateIndex (uInt index1, uInt index2) const;
253  void validateIndex (uInt index1, uInt index2, uInt index3) const;
254  // </group>
255 
256 protected:
257  // Number of elements in the array. Cached rather than computed.
258  size_t nels_p;
259  // Dimensionality of the array.
261  // Are the data contiguous?
263  // Used to hold the shape, increment into the underlying storage
264  // and originalLength of the array.
266  // Used to hold the step to next element in each dimension.
268 };
269 
270 
271 // <summary> General global functions for Arrays. </summary>
272 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tArray">
273 //
274 // <prerequisite>
275 // <li> <linkto class=Array>Array</linkto>
276 // </prerequisite>
277 //
278 // <synopsis>
279 // These are generally useful global functions which operate on all
280 // Arrays.
281 // </synopsis>
282 //
283 // <linkfrom anchor="Array general global functions" classes="Array Vector Matrix Cube">
284 // <here>Array general global functions</here> -- General global functions
285 // for Arrays.
286 // </linkfrom>
287 //
288 // <group name="Array general global functions">
289 
290 //
291 // What is the volume of an N-dimensional array.
292 // Shape[0]*Shape[1]*...*Shape[N-1]. An Array helper function.
293 //# Implemented in Array2.cc.
294 size_t ArrayVolume (uInt Ndim, const Int* Shape);
295 
296 //
297 // What is the linear index into an "Ndim" dimensional array of the given
298 // "Shape", "Origin", and "Increment" for a given IPosition Index.
299 // An Array helper function.
300 // <group>
301 //# Implemented in Array2.cc.
302 size_t ArrayIndexOffset (uInt Ndim, const ssize_t* Shape,
303  const ssize_t* Origin, const ssize_t* Inc,
304  const IPosition& Index);
305 size_t ArrayIndexOffset (uInt Ndim, const ssize_t* Shape,
306  const ssize_t* Inc, const IPosition& Index);
307 // </group>
308 
309 // </group>
310 
311 } //# NAMESPACE CASACORE - END
312 
313 #endif
IPosition endPosition() const
A convenience function: endPosition(i) = shape(i) - 1; i.e.
Bool contiguous_p
Are the data contiguous?
Definition: ArrayBase.h:262
A Vector of integers, for indexing into Array<T> objects.
Definition: IPosition.h:119
ArrayBase & operator=(const ArrayBase &)
Assignment.
void baseReform(ArrayBase &tmp, const IPosition &shape, Bool strict=True) const
Reform the array to a shape with the same nr of elements.
virtual void resize(const IPosition &newShape, Bool copyValues=False)
Resize the array and optionally copy the values.
long long Int64
Define the extra non-standard types used by Casacore (like proposed uSize, Size)
Definition: aipsxtype.h:38
int Int
Definition: aipstype.h:47
Non-templated base class for templated Array class.
Definition: ArrayBase.h:74
void throwNdimVector()
Throw expection if vector dimensionality is incorrect.
size_t nelements() const
How many elements does this array have? Product of all axis lengths.
Definition: ArrayBase.h:99
IPosition steps_p
Used to hold the step to next element in each dimension.
Definition: ArrayBase.h:267
IPosition originalLength_p
Definition: ArrayBase.h:265
uInt ndimen_p
Dimensionality of the array.
Definition: ArrayBase.h:260
StorageInitPolicy
A global enum used by some Array constructors.
Definition: ArrayBase.h:53
size_t nels_p
Number of elements in the array.
Definition: ArrayBase.h:258
virtual void assignBase(const ArrayBase &source, Bool checkType=True)
Assign the source array to this array.
void checkMatrixShape()
Check if the shape of a matrix is correct.
Bool empty() const
Is the array empty (i.e.
Definition: ArrayBase.h:106
Bool isEqual(const IPosition &other) const
Element-by-element comparison for equality.
size_t makeSubset(ArrayBase &out, const IPosition &b, const IPosition &e, const IPosition &i)
Make a subset of an array.
Bool contiguousStorage() const
Are the array data contiguous? If they are not contiguous, getStorage (see below) needs to make a cop...
Definition: ArrayBase.h:112
A global enum used by some Array/Block constructors.
Definition: Allocator.h:57
Bool isStorageContiguous() const
Determine if the storage of a subset is contiguous.
IPosition length_p
Used to hold the shape, increment into the underlying storage and originalLength of the array...
Definition: ArrayBase.h:265
virtual CountedPtr< ArrayBase > makeArray() const
Make an empty array of the same type.
void validateIndex(const IPosition &) const
size_t ArrayIndexOffset(uInt Ndim, const ssize_t *Shape, const ssize_t *Origin, const ssize_t *Inc, const IPosition &Index)
What is the linear index into an "Ndim" dimensional array of the given "Shape", "Origin", and "Increment" for a given IPosition Index.
void baseCopy(const ArrayBase &that)
Definition: ArrayBase.h:182
virtual ~ArrayBase()
Destructor.
Referenced counted pointer for constant data.
Definition: CountedPtr.h:86
void checkVectorShape()
Check if the shape of a vector is correct.
uInt ndim() const
The dimensionality of this array.
Definition: ArrayBase.h:94
void baseAddDegenerate(ArrayBase &, uInt numAxes)
These member functions return an Array reference with the specified number of extra axes...
void checkCubeShape()
Check if the shape of a cube is correct.
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:39
const Bool False
Definition: aipstype.h:41
void baseMakeSteps()
Make the indexing step sizes.
size_t ArrayVolume(uInt Ndim, const Int *Shape)
General global functions for Arrays.
Specify which elements to extract from an n-dimensional array.
Definition: Slicer.h:275
Bool conform2(const ArrayBase &other) const
Are the shapes identical?
Definition: ArrayBase.h:233
COPY is used when an internal copy of the storage is to be made.
Definition: ArrayBase.h:56
const Double e
e and functions thereof:
Share means that the Array will just use the pointer (no copy), however the Array will NOT delete it ...
Definition: ArrayBase.h:64
static uInt arrayVersion()
Array version for major change (used by ArrayIO).
Definition: ArrayBase.h:138
void validateConformance(const ArrayBase &) const
Various helper functions.
void baseNonDegenerate(const ArrayBase &other, const IPosition &ignoreAxes)
Remove the degenerate axes from the Array object.
Bool copyVectorHelper(const ArrayBase &other)
Helper function for templated Vector class.
size_t size() const
Definition: ArrayBase.h:101
const IPosition & steps() const
Return steps to be made if stepping one element in a dimension.
Definition: ArrayBase.h:132
virtual Bool ok() const
Check to see if the Array is consistent.
virtual CountedPtr< ArrayPositionIterator > makeIterator(uInt byDim) const
Create an ArrayIterator object of the correct type.
virtual CountedPtr< ArrayBase > getSection(const Slicer &) const
Get a reference to a section of an array.
const Bool True
Definition: aipstype.h:40
Bool reformOrResize(const IPosition &newShape, Bool resizeIfNeeded, uInt nReferences, Int64 nElementsAllocated, Bool copyDataIfNeeded, uInt resizePercentage)
Either reforms the array if size permits or resizes it to the new shape.
this file contains all the compiler specific defines
Definition: mainpage.dox:28
virtual void freeVStorage(const void *&storage, Bool deleteIt) const
virtual void putVStorage(void *&storage, Bool deleteAndCopy)
unsigned int uInt
Definition: aipstype.h:48
TAKE_OVER is used to indicate that the Array should just use the external storage (i...
Definition: ArrayBase.h:61
const IPosition & shape() const
The length of each axis.
Definition: ArrayBase.h:121
virtual void * getVStorage(Bool &deleteIt)
The following functions behave the same as the corresponding getStorage functions in the derived temp...