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]
//...
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.
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).
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. Later releases of the array classes might have the copy constructor actually make a copy -- comments solicited.
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.
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);
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 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. Presently the old values are not
copied over to the new array.
Resize without argument is equal to resize(IPosition()).
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.
The dimensionality of this array.
How many elements does this array have? Product of all axis lengths.
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?
The length of each axis.
A convenience function: endPosition(i) = shape(i) - 1; i.e. this
is the IPosition of the last element of the Array.
Are the array data contiguous?
If they are not contiguous, getStorage (see below)
needs to make a copy.
Get a pointer to the beginning of the array.
Note that the array may not be contiguous.
Return steps to be made if stepping one element in a dimension.
This is the 'physical' step, thus it also works correctly for
non-contiguous arrays. E.g. data() + steps(0) gives
the second element of the first axis.
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.
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.
Array version for major change (used by ArrayIO).
enum did not work properly with cfront 3.0.1), so replaced
by a static inline function. Users won't normally use this.
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.
Make the indexing step sizes.
Various helper functions.
Set the end iterator.
What is the volume of an N-dimensional array.
Shape[0]*Shape[1]*...*Shape[N-1]. An Array helper function.
What is the linear index into an "Ndim" dimensional array of the given
"Shape", "Origin", and "Increment" for a given IPosition Index.
An Array helper function.
Test conformance for two arrays of different types.
Are the shapes identical?
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(Array<T> &other)
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 unique()
Make a copy of this
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)
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
uInt ndim() const
uInt nelements() const
virtual Bool ok() const
Bool conform (const Array<T> &other) const
Bool conform (const MaskedArray<T> &other) const
const IPosition &shape() const
IPosition endPosition() const
Bool contiguousStorage() const
T* data()
T* const data() const
const IPosition& steps() 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)
static uInt arrayVersion()
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 validateConformance(const Array<T> &) const
void validateIndex(const IPosition &) const
Bool isStorageContiguous() const
void setEndIter()
General global functions for Arrays. (source)
Interface
Description
Review Status
Prerequisite
Synopsis
These are generally useful global functions which operate on all
Arrays.
Member Description
uInt ArrayVolume(uInt Ndim, const Int *Shape)
uInt ArrayIndexOffset(uInt Ndim, const Int *Shape, const Int *Origin, const Int *Inc, const IPosition &Index)
uInt ArrayIndexOffset(uInt Ndim, const Int *Shape, const Int *Inc, const IPosition &Index)
Bool conform2 (const Array<T> &left, const Array<U> &right)