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:
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.
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.
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.
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.
201 
202  // Check if the shape of a matrix is correct. Adjust it if smaller.
204 
205  // Check if the shape of a cube is correct. Adjust it if smaller.
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 (original) array.
227  size_t makeSubset (ArrayBase& out,
228  const IPosition& b,
229  const IPosition& e,
230  const IPosition& i);
231 
232  // Set the length and stride such that the diagonal of the matrices
233  // defined by two consecutive axes is formed.
234  // <src>diag</src> == 0 indicates the main diagonal, >0 above, <0 below.
235  // It returns the offset of the diagonal in the (original) array.
236  size_t makeDiagonal (uInt firstAxis, Int64 diag);
237 
238  // Are the shapes identical?
239  Bool conform2 (const ArrayBase& other) const
240  { return length_p.isEqual (other.length_p); }
241 
242  // Make the indexing step sizes.
244 
245  // Throw expection if vector dimensionality is incorrect.
247 
248  // Helper function for templated Vector class.
249  // It returns if this and other are conformant.
251 
252 public:
253  // Various helper functions.
254  // <group>
255  void validateConformance (const ArrayBase&) const;
256  void validateIndex (const IPosition&) const;
257  void validateIndex (uInt index) const;
258  void validateIndex (uInt index1, uInt index2) const;
259  void validateIndex (uInt index1, uInt index2, uInt index3) const;
260  // </group>
261 
262 protected:
263  // Number of elements in the array. Cached rather than computed.
264  size_t nels_p;
265  // Dimensionality of the array.
267  // Are the data contiguous?
269  // Used to hold the shape, increment into the underlying storage
270  // and originalLength of the array.
272  // Used to hold the step to next element in each dimension.
274 };
275 
276 
277 // <summary> General global functions for Arrays. </summary>
278 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tArray">
279 //
280 // <prerequisite>
281 // <li> <linkto class=Array>Array</linkto>
282 // </prerequisite>
283 //
284 // <synopsis>
285 // These are generally useful global functions which operate on all
286 // Arrays.
287 // </synopsis>
288 //
289 // <linkfrom anchor="Array general global functions" classes="Array Vector Matrix Cube">
290 // <here>Array general global functions</here> -- General global functions
291 // for Arrays.
292 // </linkfrom>
293 //
294 // <group name="Array general global functions">
295 
296 //
297 // What is the volume of an N-dimensional array.
298 // Shape[0]*Shape[1]*...*Shape[N-1]. An Array helper function.
299 //# Implemented in Array2.cc.
300 size_t ArrayVolume (uInt Ndim, const Int* Shape);
301 
302 //
303 // What is the linear index into an "Ndim" dimensional array of the given
304 // "Shape", "Origin", and "Increment" for a given IPosition Index.
305 // An Array helper function.
306 // <group>
307 //# Implemented in Array2.cc.
308 size_t ArrayIndexOffset (uInt Ndim, const ssize_t* Shape,
309  const ssize_t* Origin, const ssize_t* Inc,
310  const IPosition& Index);
311 size_t ArrayIndexOffset (uInt Ndim, const ssize_t* Shape,
312  const ssize_t* Inc, const IPosition& Index);
313 // </group>
314 
315 // Function to check the shapes. It throws an exception if not equal.
316 // <group>
317 void throwArrayShapes (const IPosition& shape1,
318  const IPosition& shape2,
319  const char* name);
320 inline void checkArrayShapes (const ArrayBase& left, const ArrayBase& right,
321  const char* name)
322 {
323  if (! left.shape().isEqual (right.shape())) {
324  throwArrayShapes (left.shape(), right.shape(), name);
325  }
326 }
327 // </group>
328 
329 // </group>
330 
331 } //# NAMESPACE CASACORE - END
332 
333 #endif
casacore::ArrayBase::validateConformance
void validateConformance(const ArrayBase &) const
Various helper functions.
casacore::ArrayBase::reformOrResize
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.
casacore::Slicer
Definition: Slicer.h:290
casacore::ArrayBase::baseReform
void baseReform(ArrayBase &tmp, const IPosition &shape, Bool strict=True) const
Reform the array to a shape with the same nr of elements.
casacore::ArrayBase::ok
virtual Bool ok() const
Check to see if the Array is consistent.
casacore::ArrayBase::length_p
IPosition length_p
Used to hold the shape, increment into the underlying storage and originalLength of the array.
Definition: ArrayBase.h:271
casacore::IPosition
Definition: IPosition.h:120
casacore::ArrayBase::getVStorage
virtual void * getVStorage(Bool &deleteIt)
The following functions behave the same as the corresponding getStorage functions in the derived temp...
casacore::ArrayBase::empty
Bool empty() const
Is the array empty (i.e.
Definition: ArrayBase.h:106
casacore::ArrayIndexOffset
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",...
casacore::ArrayBase::nelements
size_t nelements() const
How many elements does this array have? Product of all axis lengths.
Definition: ArrayBase.h:99
casacore::StorageInitPolicy
StorageInitPolicy
Definition: ArrayBase.h:53
casacore::ArrayBase::endPosition
IPosition endPosition() const
A convenience function: endPosition(i) = shape(i) - 1; i.e.
casacore::CountedPtr
Referenced counted pointer for constant data.
Definition: CountedPtr.h:81
casacore::ArrayBase::ndim
uInt ndim() const
The dimensionality of this array.
Definition: ArrayBase.h:94
casacore::ArrayBase
Non-templated base class for templated Array class.
Definition: ArrayBase.h:75
casacore::ArrayBase::steps_p
IPosition steps_p
Used to hold the step to next element in each dimension.
Definition: ArrayBase.h:273
casacore::TAKE_OVER
@ TAKE_OVER
TAKE_OVER is used to indicate that the Array should just use the external storage (i....
Definition: ArrayBase.h:61
casacore::ArrayBase::inc_p
IPosition inc_p
Definition: ArrayBase.h:271
casacore::ArrayBase::assignBase
virtual void assignBase(const ArrayBase &source, Bool checkType=True)
Assign the source array to this array.
casacore::ArrayBase::validateIndex
void validateIndex(uInt index) const
casacore::ArrayBase::copyVectorHelper
Bool copyVectorHelper(const ArrayBase &other)
Helper function for templated Vector class.
casacore::ArrayInitPolicy
Definition: Allocator.h:54
casacore::ArrayBase::conform2
Bool conform2(const ArrayBase &other) const
Are the shapes identical?
Definition: ArrayBase.h:239
casacore::ArrayBase::nels_p
size_t nels_p
Number of elements in the array.
Definition: ArrayBase.h:264
casacore::ArrayBase::ArrayBase
ArrayBase(const ArrayBase &other)
Copy constructor.
casacore::ArrayBase::arrayVersion
static uInt arrayVersion()
Array version for major change (used by ArrayIO).
Definition: ArrayBase.h:138
casacore::ArrayBase::validateIndex
void validateIndex(const IPosition &) const
casacore::ArrayBase::steps
const IPosition & steps() const
Return steps to be made if stepping one element in a dimension.
Definition: ArrayBase.h:132
casacore::ArrayBase::shape
const IPosition & shape() const
The length of each axis.
Definition: ArrayBase.h:121
casacore::ArrayBase::size
size_t size() const
Definition: ArrayBase.h:101
casacore::False
const Bool False
Definition: aipstype.h:44
casacore::uInt
unsigned int uInt
Definition: aipstype.h:51
casacore::ArrayBase::ArrayBase
ArrayBase()
casacore::ArrayBase::putVStorage
virtual void putVStorage(void *&storage, Bool deleteAndCopy)
casacore::ArrayBase::resize
virtual void resize(const IPosition &newShape, Bool copyValues=False)
Resize the array and optionally copy the values.
casacore::ArrayBase::baseNonDegenerate
void baseNonDegenerate(const ArrayBase &other, const IPosition &ignoreAxes)
Remove the degenerate axes from the Array object.
casacore::ArrayBase::getSection
virtual CountedPtr< ArrayBase > getSection(const Slicer &) const
Get a reference to a section of an array.
casacore::ArrayBase::baseCopy
void baseCopy(const ArrayBase &that)
Definition: ArrayBase.h:182
casacore::COPY
@ COPY
COPY is used when an internal copy of the storage is to be made.
Definition: ArrayBase.h:56
casacore::ArrayBase::baseMakeSteps
void baseMakeSteps()
Make the indexing step sizes.
casacore::ArrayBase::makeArray
virtual CountedPtr< ArrayBase > makeArray() const
Make an empty array of the same type.
casacore::IPosition::isEqual
Bool isEqual(const IPosition &other) const
Element-by-element comparison for equality.
casacore::ArrayBase::~ArrayBase
virtual ~ArrayBase()
Destructor.
casacore::ArrayBase::throwNdimVector
void throwNdimVector()
Throw expection if vector dimensionality is incorrect.
casacore::Int
int Int
Definition: aipstype.h:50
casacore
this file contains all the compiler specific defines
Definition: mainpage.dox:28
casacore::ArrayBase::baseAddDegenerate
void baseAddDegenerate(ArrayBase &, uInt numAxes)
These member functions return an Array reference with the specified number of extra axes,...
casacore::ArrayVolume
size_t ArrayVolume(uInt Ndim, const Int *Shape)
General global functions for Arrays.
casacore::True
const Bool True
Definition: aipstype.h:43
casacore::ArrayBase::getVStorage
virtual const void * getVStorage(Bool &deleteIt) const
casacore::C::e
const Double e
e and functions thereof:
casacore::ArrayBase::ArrayBase
ArrayBase(const IPosition &shape)
Create an array of the given shape, i.e.
casacore::ArrayBase::makeDiagonal
size_t makeDiagonal(uInt firstAxis, Int64 diag)
Set the length and stride such that the diagonal of the matrices defined by two consecutive axes is f...
casacore::ArrayBase::checkMatrixShape
void checkMatrixShape()
Check if the shape of a matrix is correct.
casacore::throwArrayShapes
void throwArrayShapes(const IPosition &shape1, const IPosition &shape2, const char *name)
Function to check the shapes.
casacore::Int64
long long Int64
Define the extra non-standard types used by Casacore (like proposed uSize, Size)
Definition: aipsxtype.h:38
casacore::SHARE
@ SHARE
Share means that the Array will just use the pointer (no copy), however the Array will NOT delete it ...
Definition: ArrayBase.h:64
casacore::ArrayBase::validateIndex
void validateIndex(uInt index1, uInt index2, uInt index3) const
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
casacore::ArrayBase::contiguousStorage
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
casacore::ArrayBase::ndimen_p
uInt ndimen_p
Dimensionality of the array.
Definition: ArrayBase.h:266
casacore::ArrayBase::validateIndex
void validateIndex(uInt index1, uInt index2) const
casacore::ArrayBase::originalLength_p
IPosition originalLength_p
Definition: ArrayBase.h:271
casacore::ArrayBase::makeIterator
virtual CountedPtr< ArrayPositionIterator > makeIterator(uInt byDim) const
Create an ArrayIterator object of the correct type.
casacore::ArrayBase::makeSubset
size_t makeSubset(ArrayBase &out, const IPosition &b, const IPosition &e, const IPosition &i)
Make a subset of an array.
casacore::ArrayBase::operator=
ArrayBase & operator=(const ArrayBase &)
Assignment.
casacore::ArrayBase::checkVectorShape
void checkVectorShape()
Check if the shape of a vector is correct.
casacore::ArrayBase::isStorageContiguous
Bool isStorageContiguous() const
Determine if the storage of a subset is contiguous.
casacore::ArrayBase::contiguous_p
Bool contiguous_p
Are the data contiguous?
Definition: ArrayBase.h:268
casacore::ArrayBase::checkCubeShape
void checkCubeShape()
Check if the shape of a cube is correct.
casacore::ArrayBase::resize
virtual void resize(const IPosition &newShape, Bool copyValues, ArrayInitPolicy policy)
Resize the array and optionally copy the values.
casacore::checkArrayShapes
void checkArrayShapes(const ArrayBase &left, const ArrayBase &right, const char *name)
Definition: ArrayBase.h:320
casacore::ArrayBase::freeVStorage
virtual void freeVStorage(const void *&storage, Bool deleteIt) const