#include <Array.h>
Inheritance diagram for casa::Array< T >:
Indexing into the array, and positions in general, are given with IPosition (essentially a vector of integers) objects. That is, an N-dimensional array requires a length-N IPosition to define a position within the array. Unlike C, indexing is done with (), not []. Also, the storage order is the same as in FORTRAN, i.e. memory varies most rapidly with the first index.
// axisLengths = [1,2,3,4,5] IPosition axisLengths(5, 1, 2, 3, 4, 5); Array<Int> ai(axisLengths); // ai is a 5 dimensional array of // integers; indices are 0-based // => ai.nelements() == 120 Array<Int> ai2(axisLengths); // The first element is at index 0 IPosition zero(5); zero = 0; // [0,0,0,0,0] //.\..
An Array may be standalone, or it may refer to another array, or to part of another array (by refer we mean that if you change a pixel in the current array, a pixel in the referred to array also changes, i.e. they share underlying storage). Warning: One way one array can reference another is through the copy constructor. While this might be what you want, you should probably use the reference() member function to make it explicit. The copy constructor is used when arguments are passed by value; normally functions should not pass Arrays by value, rather they should pass a reference or a const reference. On the positive side, returning an array from a function is efficient since no copying need be done.
Aside from the explicit reference() member function, a user will most commonly encounter an array which references another array when he takes an array slice (or section). A slice is a sub-region of an array (which might also have a stride: every nth row, every mth column, .\..).
IPosition lengths(3,10,20,30);
Array<Int> ai(lengths); // A 10x20x30 cube
Cube<Int> ci;
//.\..
ci.reference(ai1); // ci and ai now reference the same
// storage
ci(0,0,0) = 123; // Can use Cube indexing
ci.xyPlane(2) = 0; // and other member functions
IPosition zero(3,0,0,0);
assert(ai(zero) == 123); // True because ai, ci are references
//.\..
Array<Int> subArray;
IPosition blc(3,0,0,0), trc(3,5,5,5);
subArray.reference(ai(blc, trc));
subArray = 10; // All of subArray, which is the
// subcube from 0,0,0 to 5,5,5 in
// ai, has the value 10.
Array<Complex> array;
IPosition blc, trc, offset;
//.\..
// Copy from one region of the array into another
array(blc, trc) = array(blc+offset, trc+offset);
The Array classes are intended to operate on relatively large amounts of data. While they haven't been extensively tuned yet, they are relatively efficient in terms of speed. Presently they are not space efficient -- the overhead is about 15 words. While this will be improved (probably to about 1/2 that), these array classes are not appropriate for very large numbers of very small arrays. The Block<T> class may be what you want in this circumstance.
Element by element mathematical and logical operations are available for arrays (defined in aips/ArrayMath.h and aips/ArrayLogical.h). Because arithmetic and logical functions are split out, it is possible to create an Array<T> (and hence Vector<T> etc) for any type T that has a default constructor, assignment operator, and copy constructor. In particular, Array<String> works.
If compiled with the preprocessor symbol AIPS_DEBUG symbol, array consistency ("invariants") will be checked in most member functions, and indexing will be range-checked. This should not be defined for production runs.
A tutorial for the ArrayClasses is available in the "AIPS++ Programming Manual."
Tip: Most of the data members and functions which are "protected" should likely become "private".
Definition at line 171 of file Array.h.
Public Types | |
| typedef T | value_type |
| STL-style typedefs. | |
| typedef IteratorSTL | iterator |
| typedef ConstIteratorSTL | const_iterator |
| typedef T * | contiter |
| typedef const T * | const_contiter |
Public Member Functions | |
| Array () | |
| Result has dimensionality of zero, and nelements is zero. | |
| Array (const IPosition &shape) | |
| Create an array of the given shape, i.e. | |
| Array (const IPosition &shape, const T &initialValue) | |
| Create an array of the given shape and initialize it with the initial value. | |
| Array (const Array< T > &other) | |
| After construction, this and other reference the same storage. | |
| Array (const IPosition &shape, T *storage, StorageInitPolicy policy=COPY) | |
| Create an Array of a given shape from a pointer. | |
| Array (const IPosition &shape, const T *storage) | |
| Create an Array of a given shape from a pointer. | |
| virtual | ~Array () |
| Frees up storage only if this array was the last reference to it. | |
| virtual void | assign (const Array< T > &other) |
| Assign the other array to this array. | |
| void | set (const T &value) |
| Set every element of the array to "value." Also could use the assignment operator which assigns an array from a scalar. | |
| virtual void | reference (const Array< T > &other) |
| After invocation, this array and other reference the same storage. | |
| virtual Array< T > & | operator= (const Array< T > &other) |
| Copy the values in other to this. | |
| Array< T > & | operator= (const T &value) |
| Set every element of this array to "value". | |
| Array< T > & | operator= (const MaskedArray< T > &marray) |
| Copy to this those values in marray whose corresponding elements in marray's mask are True. | |
| Array< T > | copy () const |
| This makes a copy of the array and returns it. | |
| void | copyMatchingPart (const Array< T > &from) |
| This function copies the matching part of from array to this array. | |
| void | unique () |
| This ensures that this array does not reference any other storage. | |
| template<class U> | |
| void | tovector (std::vector< T, U > &out) const |
| Create an STL vector from an Array. | |
| Array< T > | reform (const IPosition &shape) const |
| It is occasionally useful to have an array which access the same storage appear to have a different shape. | |
| Array< T > | operator() (const Slicer &) |
| Get a reference to an array using a Slicer. | |
| uInt | nrefs () const |
| The number of references the underlying storage has assigned to it. | |
| virtual Bool | ok () const |
| Check to see if the Array is consistent. | |
| void | putStorage (T *&storage, Bool deleteAndCopy) |
| putStorage() is normally called after a call to getStorage() (cf). | |
| void | freeStorage (const T *&storage, Bool deleteIt) const |
| If deleteIt is set, delete "storage". | |
| void | apply (T(*function)(T)) |
| This version takes a function which takes a T and returns a T. | |
| void | apply (T(*function)(const T &)) |
| This version takes a function which takes a const T reference and returns a T. | |
| void | apply (const Functional< T, T > &function) |
| This version applies a functional. | |
| Array< T > | nonDegenerate (uInt startingAxis=0, Bool throwIfError=True) |
| These member functions remove degenerate (ie. | |
| const Array< T > | nonDegenerate (uInt startingAxis=0, Bool throwIfError=True) const |
| void | nonDegenerate (Array< T > &other, uInt startingAxis=0, Bool throwIfError=True) |
| Array< T > | nonDegenerate (const IPosition &ignoreAxes) |
| const Array< T > | nonDegenerate (const IPosition &ignoreAxes) const |
| void | nonDegenerate (Array< T > &other, const IPosition &ignoreAxes) |
| Array< T > | addDegenerate (uInt numAxes) |
| These member functions return an Array reference with the specified number of extra axes, all of length one, appended to the end of the Array. | |
| const Array< T > | addDegenerate (uInt numAxes) const |
| virtual void | resize () |
| Make this array a different shape. | |
| virtual void | resize (const IPosition &newShape, Bool copyValues=False) |
| T & | operator() (const IPosition &) |
| Access a single element of the array. | |
| const T & | operator() (const IPosition &) const |
| Array< T > | operator() (const IPosition &start, const IPosition &end) |
| Get a reference to an array which extends from "start" to end. | |
| Array< T > | operator() (const IPosition &start, const IPosition &end, const IPosition &inc) |
| Along the ith axis, every inc[i]'th element is chosen. | |
| MaskedArray< T > | operator() (const LogicalArray &mask) const |
| The array is masked by the input LogicalArray. | |
| MaskedArray< T > | operator() (const LogicalArray &mask) |
| MaskedArray< T > | operator() (const MaskedLogicalArray &mask) const |
| The array is masked by the input MaskedLogicalArray. | |
| MaskedArray< T > | operator() (const MaskedLogicalArray &mask) |
| Bool | conform (const Array< T > &other) const |
| Are the shapes identical? | |
| Bool | conform (const MaskedArray< T > &other) const |
| T * | data () |
| Get a pointer to the beginning of the array. | |
| const T * | data () const |
| T * | getStorage (Bool &deleteIt) |
| Generally use of this should be shunned, except to use a FORTRAN routine or something similar. | |
| const T * | getStorage (Bool &deleteIt) const |
| virtual void | takeStorage (const IPosition &shape, T *storage, StorageInitPolicy policy=COPY) |
Replace the data values with those in the pointer storage. | |
| virtual void | takeStorage (const IPosition &shape, const T *storage) |
| Since the pointer is const, a copy is always taken. | |
| iterator | begin () |
| Get the begin iterator object for any array. | |
| const_iterator | begin () const |
| iterator | end () |
| const_iterator | end () const |
| contiter | cbegin () |
| Get the begin iterator object for a contiguous array. | |
| const_contiter | cbegin () const |
| contiter | cend () |
| const_contiter | cend () const |
Protected Member Functions | |
| virtual void | doNonDegenerate (Array< T > &other, const IPosition &ignoreAxes) |
| Remove the degenerate axes from the Array object. | |
| void | makeSteps () |
| Fill the steps and the end for a derived class. | |
| void | setEndIter () |
| Set the end iterator. | |
Protected Attributes | |
| CountedPtr< Block< T > > | data_p |
| Reference counted block that contains the storage. | |
| T * | begin_p |
| This pointer is adjusted to point to the first element of the array. | |
| T * | end_p |
| The end for an STL-style iteration. | |
Friends | |
| class | ArrayIterator< T > |
| Used to iterate through Arrays. | |
| class | Matrix< T > |
| Needed to be a friend for Matrix<T>::reference(). | |
Classes | |
| class | BaseIteratorSTL |
| See the function begin() and end() for a detailed description of the STL iterator capability. More... | |
| class | ConstIteratorSTL |
| class | IteratorSTL |
| typedef T casa::Array< T >::value_type |
| typedef IteratorSTL casa::Array< T >::iterator |
| typedef ConstIteratorSTL casa::Array< T >::const_iterator |
| typedef T* casa::Array< T >::contiter |
| typedef const T* casa::Array< T >::const_contiter |
| casa::Array< T >::Array | ( | ) |
Result has dimensionality of zero, and nelements is zero.
| casa::Array< T >::Array | ( | const IPosition & | shape | ) | [explicit] |
Create an array of the given shape, i.e.
after construction array.ndim() == shape.nelements() and array.shape() == shape. The origin of the Array is zero.
| casa::Array< T >::Array | ( | const IPosition & | shape, | |
| const T & | initialValue | |||
| ) |
Create an array of the given shape and initialize it with the initial value.
| casa::Array< T >::Array | ( | const Array< T > & | other | ) |
After construction, this and other reference the same storage.
| casa::Array< T >::Array | ( | const IPosition & | shape, | |
| T * | storage, | |||
| StorageInitPolicy | policy = COPY | |||
| ) |
Create an Array of a given shape from a pointer.
| casa::Array< T >::Array | ( | const IPosition & | shape, | |
| const T * | storage | |||
| ) |
Create an Array of a given shape from a pointer.
Because the pointer is const, a copy is always made.
| virtual casa::Array< T >::~Array | ( | ) | [virtual] |
Frees up storage only if this array was the last reference to it.
| virtual void casa::Array< T >::assign | ( | const Array< T > & | other | ) | [virtual] |
Assign the other array to this array.
If the shapes mismatch, this array is resized.
| void casa::Array< T >::set | ( | const T & | value | ) |
Set every element of the array to "value." Also could use the assignment operator which assigns an array from a scalar.
| void casa::Array< T >::apply | ( | T(*)(T) | function | ) |
This version takes a function which takes a T and returns a T.
| void casa::Array< T >::apply | ( | T(*)(const T &) | function | ) |
This version takes a function which takes a const T reference and returns a T.
| void casa::Array< T >::apply | ( | const Functional< T, T > & | function | ) |
This version applies a functional.
| virtual void casa::Array< T >::reference | ( | const Array< T > & | other | ) | [virtual] |
After invocation, this array and other reference the same storage.
That is, modifying an element through one will show up in the other. The arrays appear to be identical; they have the same shape.
Please note that this function makes it possible to reference a const Array, thus effectively it makes a const Array non-const. Although this may seem undesirable at first sight, it is necessary to be able to make references to temporary Array objects, in particular to Array slices. Otherwise one first needs to use the copy constructor.
| virtual Array<T>& casa::Array< T >::operator= | ( | const Array< T > & | other | ) | [virtual] |
Copy the values in other to this.
If the array on the left hand side has no elements, then it is resized to be the same size as as the array on the right hand side. Otherwise, the arrays must conform (same shapes).
IPosition shape(2,10,10); // some shape Array<Double> ad(shape); //.\.. Array<Double> ad2; // N.B. ad2.nelements() == 0 ad2 = ad; // ad2 resizes, then elements // are copied. shape = 20; Array<Double> ad3(shape); ad3 = ad; // Error: arrays do not conform
| Array<T>& casa::Array< T >::operator= | ( | const T & | value | ) |
Set every element of this array to "value".
In other words, a scalar behaves as if it were a constant conformant array.
| Array<T>& casa::Array< T >::operator= | ( | const MaskedArray< T > & | marray | ) |
Copy to this those values in marray whose corresponding elements in marray's mask are True.
| Array<T> casa::Array< T >::copy | ( | ) | const |
This makes a copy of the array and returns it.
This can be useful for, e.g. making working copies of function arguments that you can write into.
void someFunction(const Array<Int> &arg) { Array<Int> tmp(arg.copy()); // .\.. }
void someFunction(const Array<Int> &arg) { Array<Int> tmp; tmp = arg; // .\.. }
Referenced by casa::ArrayMath_global_functions_Array_mathematical_operations::cube(), and casa::ArrayMath_global_functions_Array_mathematical_operations::square().
| void casa::Array< T >::copyMatchingPart | ( | const Array< T > & | from | ) |
This function copies the matching part of from array to this array.
The matching part is the part with the minimum size for each axis. E.g. if this array has shape [4,5,6] and from array has shape [7,3], the matching part has shape [4,3].
Note it is used by the resize function if copyValues==True.
| void casa::Array< T >::unique | ( | ) |
This ensures that this array does not reference any other storage.
Tip: When a section is taken of an array with non-unity strides, storage can be wasted if the array, which originally contained all the data, goes away. unique() also reclaims storage. This is an optimization users don't normally need to understand.
IPosition shape(.\..), blc(.\..), trc(.\..), inc(.\..);
Array<Float> af(shape);
inc = 2; // or anything > 1
Array<Float> aSection.reference(af(blc, trc, inc));
af.reference(anotherArray);
// aSection now references storage that has a stride
// in it, but nothing else is. Storage is wasted.
aSection.unique();
| void casa::Array< T >::tovector | ( | std::vector< T, U > & | out | ) | const |
| Array<T> casa::Array< T >::reform | ( | const IPosition & | shape | ) | const |
It is occasionally useful to have an array which access the same storage appear to have a different shape.
For example, turning an N-dimensional array into a Vector.
When the array data are contiguous, the array can be reshaped to any form as long as the number of elements stays the same. When not contiguous, it is only possible to remove or add axes with length 1.
| Array<T> casa::Array< T >::nonDegenerate | ( | uInt | startingAxis = 0, |
|
| Bool | throwIfError = True | |||
| ) |
These member functions remove degenerate (ie.
length==1) axes from Arrays. Only axes greater than startingAxis are considered (normally one wants to remove trailing axes. The first two of these function return an Array reference with axes removed. The last of these functions returns a reference to the 'other' array with degenerated axes removed.
Unless throwIfError is False, an exception will be thrown if startingAxis exceeds the array's dimensionality.
The functions with argument ignoreAxes do not consider the axes given in that argument. Caution: When the two functions returning void throw are invoked on a derived object (e.g. Matrix), an exception is thrown if removing the degenerate axes from other does not result in a correct number of axes.
| const Array<T> casa::Array< T >::nonDegenerate | ( | uInt | startingAxis = 0, |
|
| Bool | throwIfError = True | |||
| ) | const |
| void casa::Array< T >::nonDegenerate | ( | Array< T > & | other, | |
| uInt | startingAxis = 0, |
|||
| Bool | throwIfError = True | |||
| ) |
| Array<T> casa::Array< T >::nonDegenerate | ( | const IPosition & | ignoreAxes | ) |
| const Array<T> casa::Array< T >::nonDegenerate | ( | const IPosition & | ignoreAxes | ) | const |
| void casa::Array< T >::nonDegenerate | ( | Array< T > & | other, | |
| const IPosition & | ignoreAxes | |||
| ) | [inline] |
| Array<T> casa::Array< T >::addDegenerate | ( | uInt | numAxes | ) |
| const Array<T> casa::Array< T >::addDegenerate | ( | uInt | numAxes | ) | const |
| virtual void casa::Array< T >::resize | ( | ) | [virtual] |
Make this array a different shape.
If copyValues==True the old values are copied over to the new array. Copying is done on a per axis basis, thus a subsection with the minimum of the old and new shape is copied.
Resize without argument is equal to resize(IPosition()).
It is important to note that if multiple Array objects reference the same data storage, this Array object still references the same data storage as the other Array objects if the shape does not change. Otherwise this Array object references newly allocated storage, while the other Array objects still reference the existing data storage.
If you want to be sure that the data storage of this Array object is not referenced by other Array objects, the function unique should be called first.
| virtual void casa::Array< T >::resize | ( | const IPosition & | newShape, | |
| Bool | copyValues = False | |||
| ) | [virtual] |
| T& casa::Array< T >::operator() | ( | const IPosition & | ) |
| const T& casa::Array< T >::operator() | ( | const IPosition & | ) | const |
| Array<T> casa::Array< T >::operator() | ( | const IPosition & | start, | |
| const IPosition & | end | |||
| ) |
Get a reference to an array which extends from "start" to end.
"
| Array<T> casa::Array< T >::operator() | ( | const IPosition & | start, | |
| const IPosition & | end, | |||
| const IPosition & | inc | |||
| ) |
Along the ith axis, every inc[i]'th element is chosen.
| Array<T> casa::Array< T >::operator() | ( | const Slicer & | ) |
Get a reference to an array using a Slicer.
| MaskedArray<T> casa::Array< T >::operator() | ( | const LogicalArray< T > & | mask | ) | const |
The array is masked by the input LogicalArray.
This mask must conform to the array.
| MaskedArray<T> casa::Array< T >::operator() | ( | const LogicalArray< T > & | mask | ) |
| MaskedArray<T> casa::Array< T >::operator() | ( | const MaskedLogicalArray< T > & | mask | ) | const |
The array is masked by the input MaskedLogicalArray.
The mask is effectively the AND of the internal LogicalArray and the internal mask of the MaskedLogicalArray. The MaskedLogicalArray must conform to the array.
| MaskedArray<T> casa::Array< T >::operator() | ( | const MaskedLogicalArray< T > & | mask | ) |
| uInt casa::Array< T >::nrefs | ( | ) | const |
The number of references the underlying storage has assigned to it.
It is 1 unless there are outstanding references to the storage (e.g., through a slice). Normally you have no need to do this since the arrays handle all of the references for you.
| virtual Bool casa::Array< T >::ok | ( | ) | const [virtual] |
Check to see if the Array is consistent.
This is about the same thing as checking for invariants. If AIPS_DEBUG is defined, this is invoked after construction and on entry to most member functions.
Reimplemented from casa::ArrayBase.
| Bool casa::Array< T >::conform | ( | const Array< T > & | other | ) | const [inline] |
| Bool casa::Array< T >::conform | ( | const MaskedArray< T > & | other | ) | const |
| T* casa::Array< T >::data | ( | ) | [inline] |
| const T* casa::Array< T >::data | ( | ) | const [inline] |
| T* casa::Array< T >::getStorage | ( | Bool & | deleteIt | ) |
Generally use of this should be shunned, except to use a FORTRAN routine or something similar.
Because you can't know the state of the underlying data layout (in particular, if there are increments) sometimes the pointer returned will be to a copy, but often this won't be necessary. A boolean is returned which tells you if this is a copy (and hence the storage must be deleted). Note that if you don't do anything unusual, getStorage followed by freeStorage or putStorage will do the deletion for you (if required). e.g.:
Array<Int> a(shape); .\..
Bool deleteIt; Int *storage = a.getStorage(deleteIt);
foo(storage, a.nelements()); a.puStorage(storage, deleteIt);
// or a.freeStorage(storage, deleteIt) if a is const.
It would probably be useful to have corresponding "copyin" "copyout" functions that used a user supplied buffer. Note that deleteIt is set in this function.
Referenced by casa::IonosphModel::setAlt().
| const T* casa::Array< T >::getStorage | ( | Bool & | deleteIt | ) | const |
| void casa::Array< T >::putStorage | ( | T *& | storage, | |
| Bool | deleteAndCopy | |||
| ) |
putStorage() is normally called after a call to getStorage() (cf).
The "storage" pointer is set to zero.
| void casa::Array< T >::freeStorage | ( | const T *& | storage, | |
| Bool | deleteIt | |||
| ) | const |
If deleteIt is set, delete "storage".
Normally freeStorage calls will follow calls to getStorage. The reason the pointer is "const" is because only const pointers are released from const arrays. The "storage" pointer is set to zero.
Referenced by casa::IonosphModel::setAlt().
| virtual void casa::Array< T >::takeStorage | ( | const IPosition & | shape, | |
| T * | storage, | |||
| StorageInitPolicy | policy = COPY | |||
| ) | [virtual] |
Replace the data values with those in the pointer storage.
The results are undefined is storage does not point at nelements() or more data elements. After takeStorage() is called, unique() is True.
| virtual void casa::Array< T >::takeStorage | ( | const IPosition & | shape, | |
| const T * | storage | |||
| ) | [virtual] |
Since the pointer is const, a copy is always taken.
| iterator casa::Array< T >::begin | ( | ) | [inline] |
| const_iterator casa::Array< T >::begin | ( | ) | const [inline] |
| iterator casa::Array< T >::end | ( | ) | [inline] |
| const_iterator casa::Array< T >::end | ( | ) | const [inline] |
| contiter casa::Array< T >::cbegin | ( | ) | [inline] |
| const_contiter casa::Array< T >::cbegin | ( | ) | const [inline] |
| contiter casa::Array< T >::cend | ( | ) | [inline] |
| const_contiter casa::Array< T >::cend | ( | ) | const [inline] |
| virtual void casa::Array< T >::doNonDegenerate | ( | Array< T > & | other, | |
| const IPosition & | ignoreAxes | |||
| ) | [protected, virtual] |
Remove the degenerate axes from the Array object.
This is the implementation of the nonDegenerate functions. It has a different name to be able to make it virtual without having the "hide virtual function" message when compiling derived classes.
Referenced by casa::Array< ArgType >::nonDegenerate().
| void casa::Array< T >::makeSteps | ( | ) | [inline, protected] |
| void casa::Array< T >::setEndIter | ( | ) | [inline, protected] |
Set the end iterator.
Definition at line 743 of file Array.h.
Referenced by casa::Array< ArgType >::makeSteps().
friend class ArrayIterator< T > [friend] |
Used to iterate through Arrays.
Derived classes VectorIterator and MatrixIterator are probably more useful.
friend class Matrix< T > [friend] |
CountedPtr<Block<T> > casa::Array< T >::data_p [protected] |
T* casa::Array< T >::begin_p [protected] |
This pointer is adjusted to point to the first element of the array.
It is not necessarily the same thing as data->storage() since this array might be a section, e.g. have a blc which shifts us forward into the block.
Definition at line 732 of file Array.h.
Referenced by casa::Array< ArgType >::cbegin(), casa::Array< ArgType >::data(), casa::Vector< ArgType >::operator()(), casa::Matrix< std::complex< Float > >::operator()(), casa::Cube< std::complex< Float > >::operator()(), and casa::Array< ArgType >::setEndIter().
T* casa::Array< T >::end_p [protected] |