Array
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.
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).
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,
...).
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
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
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."
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.
Create an array of the given shape and initialize it with the
initial value.
After construction, this and other reference the same storage.
Create an Array of a given shape from a pointer.
Frees up storage only if this array was the last reference to it.
Assign the other array to this array.
If the shapes mismatch, this array is resized.
Set every element of the array to "value." Also could use the
assignment operator which assigns an array from a scalar.
Apply the function to every element of the array. This modifies
the array in place.
This version takes a function which takes a T and returns a T.
Apply the function to every element of the array. This modifies
the array in place.
This version takes a function which takes a const T reference and
returns a T.
Apply the function to every element of the array. This modifies
the array in place.
This version applies a functional.
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.
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).
Set every element of this array to "value". In other words, a scalar
behaves as if it were a constant conformant array.
Copy to this those values in marray whose corresponding elements
in marray's mask are True.
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.
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].
This ensures that this array does not reference any other storage.
Create an STL vector from an Array. The created vector is a linear
representation of the Array memory. See
Vector for
details of the operation and its reverse (i.e. creating a
Vector from a vector), and for details of
definition and instantiation.
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.
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.
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. Note that the reform function can also be
used to add extra axes.
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.
Access a single element of the array. This is relatively
expensive. Extensive indexing should be done through one
of the Array specializations (Vector, Matrix, Cube). If
AIPS_DEBUG is defined, index checking will be performed.
Get a reference to an array which extends from "start" to end."
Along the ith axis, every inc[i]'th element is chosen.
Get a reference to an array which extends from "start" to end."
Get a reference to an array using a Slicer.
The array is masked by the input LogicalArray.
This mask must conform to the array.
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.
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.
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.
Are the shapes identical?
Get a pointer to the beginning of the array.
Note that the array may not be contiguous.
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.:
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.
putStorage() is normally called after a call to getStorage() (cf).
The "storage" pointer is set to zero.
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.
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.
Since the pointer is const, a copy is always taken.
Define the STL-style iterators.
It makes it possible to iterate through all data elements of an array.
STL-style typedefs.
Define the STL-style iterators.
It makes it possible to iterate through all data elements of an array.
Get the begin iterator object for any array.
Define the STL-style iterators.
It makes it possible to iterate through all data elements of an array.
Fill the steps and the end for a derived class.
Set the end iterator.
// 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]
//...
Indexing into an N-dimensional array is relatively expensive. Normally
you will index into a Vector, Matrix, or Cube. These may be obtained from
an N-dimensional array by creating a reference, or by using an
ArrayIterator. The "shape" of the array is an IPosition which gives the
length of each axis.
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.
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.
While the last example has an array slice referenced explicitly by another
array variable, normally the user will often only use the slice as
a temporary in an expresion, for example:
Array<Complex> array;
IPosition blc, trc, offset;
//...
// Copy from one region of the array into another
array(blc, trc) = array(blc+offset, trc+offset);
Most of the data members and functions which are "protected" should
likely become "private".
Member Description
Array()
Result has dimensionality of zero, and nelements is zero.
explicit Array(const IPosition &shape)
Array(const IPosition &shape, const T &initialValue)
Array(const Array<T> &other)
Array(const IPosition &shape, T *storage, StorageInitPolicy policy = COPY)
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 ~Array()
virtual void assign (const Array<T>& other)
void set(const T &value)
void apply(T (*function)(T))
void apply(T (*function)(const T &))
void apply(const Functional<T,T> &function)
virtual void reference(const Array<T> &other)
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> &operator=(const Array<T> &other)
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
Note that the assign function can be used to assign a
non-conforming array.
Array<T> &operator=(const T &value)
Array<T> &operator= (const MaskedArray<T> &marray)
Thrown Exceptions
Array<T> copy() const
void someFunction(const Array<Int> &arg)
{
Array<Int> tmp(arg.copy());
// ...
}
Note that since the copy constructor makes a reference, if we just
created used to copy constructor, modifying "tmp" would also
modify "arg". Clearly another alternative would simply be:
void someFunction(const Array<Int> &arg)
{
Array<Int> tmp;
tmp = arg;
// ...
}
which likely would be simpler to understand. (Should copy()
be deprecated and removed?)
void copyMatchingPart (const Array<T> &from)
Make a copy of this
Note it is used by the resize function if
copyValues==True.
void unique()
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();
template <class U> void tovector(vector<T, U> &out) const
Array<T> reform(const IPosition &shape) const
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.
IPosition squareShape(2,5,5);
Array<Float> square(squareShape);
IPosition lineShape(1,25);
Vector<Float> line(square.reform(lineShape));
// "square"'s storage may now be accessed through Vector "line"
Array<T> nonDegenerate(uInt startingAxis=0, Bool throwIfError=True)
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)
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.
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.
Array<T> addDegenerate(uInt numAxes)
const Array<T> addDegenerate(uInt numAxes) const
virtual void resize()
virtual void resize(const IPosition &newShape, Bool copyValues=False)
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.
T &operator()(const IPosition &)
const T &operator()(const IPosition &) const
Array<T> operator()(const IPosition &start, const IPosition &end, const IPosition &inc)
Array<T> operator()(const IPosition &start, const IPosition &end)
Array<T> operator()(const Slicer&)
MaskedArray<T> operator() (const LogicalArray &mask) const
MaskedArray<T> operator() (const LogicalArray &mask)
MaskedArray<T> operator() (const MaskedLogicalArray &mask) const
MaskedArray<T> operator() (const MaskedLogicalArray &mask)
uInt nrefs() const
virtual Bool ok() const
Bool conform (const Array<T> &other) const
Bool conform (const MaskedArray<T> &other) const
T* data()
T* const data() const
T *getStorage(Bool &deleteIt)
const T *getStorage(Bool &deleteIt) const
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.
NB: However, if you only use getStorage, you will have to delete the
pointer yourself using freeStorage().
void putStorage(T *&storage, Bool deleteAndCopy)
void freeStorage(const T *&storage, Bool deleteIt) const
virtual void takeStorage(const IPosition &shape, const T *storage)
virtual void takeStorage(const IPosition &shape, T *storage, StorageInitPolicy policy = COPY)
Array<Int> arr(shape);
for (Array<Int>::iterator iter=arr.begin(); iter!=arr.end(); iter++) {
*iter += 1;
}
iterator begin()
const_iterator begin() const
const T* const end() const
Array<Int> arr(shape);
for (Array<Int>::iterator iter=arr.begin(); iter!=arr.end(); iter++) {
*iter += 1;
}
contiter cbegin()
const_contiter cbegin() const
const contiter cend()
const const_contiter cend() const
Array<Int> arr(shape);
for (Array<Int>::iterator iter=arr.begin(); iter!=arr.end(); iter++) {
*iter += 1;
}
virtual void doNonDegenerate(Array<T> &other, const IPosition &ignoreAxes)
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.
void makeSteps()
void setEndIter()