template <class T, class U> class vector; More...

#include <Array.h>

Inheritance diagram for casa::Array< T >:

Classes
class	BaseIteratorSTL
	See the function begin() and end() for a detailed description of the STL iterator capability. More...
class	ConstIteratorSTL
class	IteratorSTL
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.
void	apply (T(*function)(T))
	Apply the function to every element of the array.
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.
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 (vector< T, U > &out) const
	Create an STL vector from an Array.
vector< T >	tovector () const
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 >	nonDegenerate (uInt startingAxis=0, Bool throwIfError=True) const
	These member functions remove degenerate (ie.
Array< T >	nonDegenerate (const IPosition &ignoreAxes) const
void	nonDegenerate (const Array< T > &other, uInt startingAxis=0, Bool throwIfError=True)
void	nonDegenerate (const Array< T > &other, const IPosition &ignoreAxes)
void	removeDegenerate (uInt startingAxis=0, Bool throwIfError=True)
	Remove degenerate axes from this Array object.
void	removeDegenerate (const IPosition &ignoreAxes)
const Array< T >	addDegenerate (uInt numAxes) const
	This member function returns an Array reference with the specified number of extra axes, all of length one, appended to the end of the Array.
Array< T >	addDegenerate (uInt numAxes)
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 section extending from start to end (inclusive).
const Array< T >	operator() (const IPosition &start, const IPosition &end) const
Array< T >	operator() (const IPosition &start, const IPosition &end, const IPosition &inc)
	Along the ith axis, every inc[i]'th element is chosen.
const Array< T >	operator() (const IPosition &start, const IPosition &end, const IPosition &inc) const
Array< T >	operator() (const Slicer &)
	Get a reference to an array section using a Slicer.
const Array< T >	operator() (const Slicer &) const
virtual ArrayBase *	getSection (const Slicer &)
	Get a reference to a section of an array.
Array< T >	operator[] (uInt i) const
	Get the subset given by the i-th value of the last axis.
const MaskedArray< T >	operator() (const LogicalArray &mask) const
	The array is masked by the input LogicalArray.
MaskedArray< T >	operator() (const LogicalArray &mask)
const MaskedArray< T >	operator() (const MaskedLogicalArray &mask) const
	The array is masked by the input MaskedLogicalArray.
MaskedArray< T >	operator() (const MaskedLogicalArray &mask)
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.
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
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".
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.
virtual ArrayPositionIterator *	makeIterator (uInt byDim)
	Create an ArrayIterator object of the correct type.
Friends
class	ArrayIterator< T >
	Used to iterate through Arrays.
class	Matrix< T >
	Needed to be a friend for Matrix<T>::reference()
typedef T	value_type
	Define the STL-style iterator functions (only forward iterator).
typedef IteratorSTL	iterator
typedef ConstIteratorSTL	const_iterator
typedef T *	contiter
typedef const T *	const_contiter
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.
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
virtual void	doNonDegenerate (const Array< T > &other, const IPosition &ignoreAxes)

void	makeSteps ()
	Fill the steps and the end for a derived class.
void	setEndIter ()
	Set the end iterator.

Detailed Description

template<class T>
class casa::Array< T >

template <class T, class U> class vector;

A templated N-D Array class with zero origin Array<T> is a templated, N-dimensional, Array class. The origin is zero, but by default indices are zero-based. This Array class is the base class for specialized Vector<T>, Matrix<T>, and Cube<T> classes.

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).
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.

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<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";

To Do

Integrate into the Lattice hierarchy
Factor out the common functions (shape etc) into a type-independent base class.

Definition at line 169 of file Array.h.

Member Typedef Documentation

template<class T>

typedef const T* casa::Array< T >::const_contiter

Definition at line 716 of file Array.h.

template<class T>

typedef ConstIteratorSTL casa::Array< T >::const_iterator

Definition at line 714 of file Array.h.

template<class T>

typedef T* casa::Array< T >::contiter

Definition at line 715 of file Array.h.

template<class T>

typedef IteratorSTL casa::Array< T >::iterator

Definition at line 713 of file Array.h.

template<class T>

typedef T casa::Array< T >::value_type

Define the STL-style iterator functions (only forward iterator).

   It makes it possible to iterate through all data elements of an array
   and to use it common STL functions.
   The end() function is relatively expensive, so it should not be
   used inside a for statement. It is much better to call it beforehand
   as shown in the example below. Furthermore it is very important to
   use <tt>++iter</tt>, because <tt>iter++</tt> is 4 times slower.

         Array<Int> arr(shape);
         Array<Int>::iterator iterend(arr.end());
         for (Array<Int>::iterator iter=arr.begin(); iter!=iterend; ++iter) {
           *iter += 1;
         }

The Array class supports random access, so in principle a random iterator could be implemented, but its performance would not be great, especially for non-contiguous arrays.
Some other STL like functions exist for performance reasons. If the array is contiguous, it is possible to use the cbegin and cend functions which are about 10% faster. STL-style typedefs.

Definition at line 712 of file Array.h.

Constructor & Destructor Documentation

template<class T>

casa::Array< T >::Array ( )

Result has dimensionality of zero, and nelements is zero.

template<class T>

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.

template<class T>

casa::Array< T >::Array	(	const IPosition &	shape,
		const T &	initialValue
	)

Create an array of the given shape and initialize it with the initial value.

template<class T>

casa::Array< T >::Array ( const Array< T > & other )

After construction, this and other reference the same storage.

template<class T>

casa::Array< T >::Array	(	const IPosition &	shape,
		T *	storage,
		StorageInitPolicy	policy = `COPY`
	)

Create an Array of a given shape from a pointer.

template<class T>

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.

template<class T>

virtual casa::Array< T >::~Array ( ) [virtual]

Frees up storage only if this array was the last reference to it.

Member Function Documentation

template<class T>

const Array<T> casa::Array< T >::addDegenerate ( uInt numAxes ) const

This member function returns 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.

template<class T>

Array<T> casa::Array< T >::addDegenerate ( uInt numAxes )

template<class T>

void casa::Array< T >::apply ( T(*)(T) function )

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.

template<class 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.

template<class T>

void casa::Array< T >::apply ( const Functional< T, T > & function )

This version applies a functional.

template<class T>

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.

template<class T>

iterator casa::Array< T >::begin ( ) [inline]

Get the begin iterator object for any array.

Definition at line 720 of file Array.h.

Referenced by casa::ArrayMath_global_functions_Array_mathematical_operations::arrayContTransform(), and casa::ArrayMath_global_functions_Array_mathematical_operations::arrayTransformInPlace().

template<class T>

const_iterator casa::Array< T >::begin ( ) const [inline]

Definition at line 722 of file Array.h.

template<class T>

contiter casa::Array< T >::cbegin ( ) [inline]

Get the begin iterator object for a contiguous array.

Definition at line 732 of file Array.h.

Referenced by casa::ArrayMath_global_functions_Array_mathematical_operations::arrayContTransform(), and casa::ArrayMath_global_functions_Array_mathematical_operations::arrayTransformInPlace().

template<class T>

const_contiter casa::Array< T >::cbegin ( ) const [inline]

Definition at line 734 of file Array.h.

template<class T>

contiter casa::Array< T >::cend ( ) [inline]

Definition at line 736 of file Array.h.

Referenced by casa::ArrayMath_global_functions_Array_mathematical_operations::arrayContTransform(), and casa::ArrayMath_global_functions_Array_mathematical_operations::arrayTransformInPlace().

template<class T>

const_contiter casa::Array< T >::cend ( ) const [inline]

Definition at line 738 of file Array.h.

template<class T>

Bool casa::Array< T >::conform ( const Array< T > & other ) const [inline]

Are the shapes identical?

Definition at line 479 of file Array.h.

template<class T>

Bool casa::Array< T >::conform ( const MaskedArray< T > & other ) const

template<class T>

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());
            // ..\.
        }

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?)

Referenced by casa::VisBufferAsync::copyVector().

template<class T>

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.

template<class T>

T* casa::Array< T >::data ( ) [inline]

Get a pointer to the beginning of the array.

Note that the array may not be contiguous.

Definition at line 487 of file Array.h.

Referenced by casa::ArrayLogical_global_functions_Array_logical_operations::allSame(), casa::LSQaips::getErrors(), casa::HDF5Record::readArr(), casa::LSQaips::solve(), and casa::HDF5Record::writeArr().

template<class T>

const T* casa::Array< T >::data ( ) const [inline]

Definition at line 489 of file Array.h.

template<class T>

virtual void casa::Array< T >::doNonDegenerate	(	const 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().

template<class T>

iterator casa::Array< T >::end ( ) [inline]

Definition at line 724 of file Array.h.

Referenced by casa::ArrayMath_global_functions_Array_mathematical_operations::arrayContTransform(), and casa::ArrayMath_global_functions_Array_mathematical_operations::arrayTransformInPlace().

template<class T>

const_iterator casa::Array< T >::end ( ) const [inline]

Definition at line 726 of file Array.h.

template<class T>

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.

template<class T>

virtual ArrayBase* casa::Array< T >::getSection ( const Slicer & ) [virtual]

Get a reference to a section of an array.

This is the same as operator().

Reimplemented from casa::ArrayBase.

template<class T>

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.

NB: However, if you only use getStorage, you will have to delete the pointer yourself using freeStorage().

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::VisibilityResamplerBase::cacheAxisIncrements().

template<class T>

const T* casa::Array< T >::getStorage ( Bool & deleteIt ) const

template<class T>

virtual ArrayPositionIterator* casa::Array< T >::makeIterator ( uInt byDim ) [virtual]

Create an ArrayIterator object of the correct type.

Reimplemented from casa::ArrayBase.

template<class T>

void casa::Array< T >::makeSteps ( ) [inline, protected]

Fill the steps and the end for a derived class.

Definition at line 768 of file Array.h.

template<class T>

Array<T> casa::Array< T >::nonDegenerate	(	uInt	startingAxis = `0`,
		Bool	throwIfError = `True`
	)		const

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 functions return an Array reference with axes removed. The latter two functions let this Array object reference 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. In this way it can be achieved that degenerate axes are kept.
Caution: When the two functions returning void 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;

template<class T>

Array<T> casa::Array< T >::nonDegenerate ( const IPosition & ignoreAxes ) const

template<class T>

void casa::Array< T >::nonDegenerate	(	const Array< T > &	other,
		uInt	startingAxis = `0`,
		Bool	throwIfError = `True`
	)

template<class T>

void casa::Array< T >::nonDegenerate	(	const Array< T > &	other,
		const IPosition &	ignoreAxes
	)		`[inline]`

Definition at line 364 of file Array.h.

template<class T>

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.

template<class T>

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.

template<class T>

T& casa::Array< T >::operator() ( const 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.

template<class T>

const T& casa::Array< T >::operator() ( const IPosition & ) const

template<class T>

Array<T> casa::Array< T >::operator()	(	const IPosition &	start,
		const IPosition &	end
	)

Get a reference to an array section extending from start to end (inclusive).

template<class T>

const Array<T> casa::Array< T >::operator()	(	const IPosition &	start,
		const IPosition &	end
	)		const

template<class T>

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.

template<class T>

const Array<T> casa::Array< T >::operator()	(	const IPosition &	start,
		const IPosition &	end,
		const IPosition &	inc
	)		const

template<class T>

Array<T> casa::Array< T >::operator() ( const Slicer & )

Get a reference to an array section using a Slicer.

template<class T>

const Array<T> casa::Array< T >::operator() ( const Slicer & ) const

template<class T>

const 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.

template<class T>

MaskedArray<T> casa::Array< T >::operator() ( const LogicalArray< T > & mask )

template<class T>

const 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.

template<class T>

MaskedArray<T> casa::Array< T >::operator() ( const MaskedLogicalArray< T > & mask )

template<class T>

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

Note that the assign function can be used to assign a non-conforming array.

template<class T>

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.

template<class T>

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.

Thrown Exceptions

ArrayConformanceError

template<class T>

Array<T> casa::Array< T >::operator[] ( uInt i ) const

Get the subset given by the i-th value of the last axis.

So for a cube it returns the i-th xy plane. For a Matrix it returns the i-th row. The returned array references the original array data; its dimensionality is one less. For a 1-dim array it still returns a 1-dim array.
Note: This function should not be used in tight loops as it is (much) slower than iterating using begin() and end(), ArrayIter, or ArrayAccessor;

template<class T>

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.

template<class T>

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.

Referenced by casa::ValueHolder::getValue(), and casa::RecordInterface::toArray().

template<class T>

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.

        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"

template<class T>

void casa::Array< T >::removeDegenerate	(	uInt	startingAxis = `0`,
		Bool	throwIfError = `True`
	)

Remove degenerate axes from this Array object.

Note it does not make sense to use these functions on a derived object like Matrix, because it is not possible to remove axes from them.

template<class T>

void casa::Array< T >::removeDegenerate ( const IPosition & ignoreAxes )

template<class T>

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.

Referenced by casa::SynthesisUtils::SETVEC().

template<class T>

virtual void casa::Array< T >::resize	(	const IPosition &	newShape,
		Bool	copyValues = `False`
	)		`[virtual]`

template<class T>

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.

Referenced by casa::CTPatchedInterp::setDefFldMap().

template<class T>

void casa::Array< T >::setEndIter ( ) [inline, protected]

Set the end iterator.

Definition at line 772 of file Array.h.

Referenced by casa::Array< ArgType >::makeSteps().

template<class T>

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.

template<class T>

virtual void casa::Array< T >::takeStorage	(	const IPosition &	shape,
		const T *	storage
	)		`[virtual]`

Since the pointer is const, a copy is always taken.

template<class T>

template<class U >

void casa::Array< T >::tovector ( vector< T, U > & out ) const

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.

template<class T>

vector<T> casa::Array< T >::tovector ( ) const

template<class T>

void casa::Array< T >::unique ( )

This ensures that this array does not reference any other storage.

   <br><strong>Tip:</strong><em> 
          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();

Friends And Related Function Documentation

template<class T>

friend class ArrayIterator< T > [friend]

Used to iterate through Arrays.

Derived classes VectorIterator and MatrixIterator are probably more useful.

Definition at line 542 of file Array.h.

template<class T>

friend class Matrix< T > [friend]

Needed to be a friend for Matrix<T>::reference()

Definition at line 548 of file Array.h.

Member Data Documentation

template<class T>

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 761 of file Array.h.

Referenced by casa::Cube< Complex >::at(), casa::Array< ArgType >::cbegin(), casa::Array< ArgType >::data(), casa::Cube< Complex >::operator()(), casa::Matrix< uInt >::operator()(), casa::Vector< ArgType >::operator()(), casa::Vector< ArgType >::operator[](), and casa::Array< ArgType >::setEndIter().

template<class T>

CountedPtr<Block<T> > casa::Array< T >::data_p [protected]

Reference counted block that contains the storage.

Definition at line 755 of file Array.h.

template<class T>

T* casa::Array< T >::end_p [protected]

The end for an STL-style iteration.

Definition at line 764 of file Array.h.

Referenced by casa::Array< ArgType >::cend(), casa::Array< ArgType >::end(), and casa::Array< ArgType >::setEndIter().

The documentation for this class was generated from the following file:

casacore/casa/Arrays/Array.h

Classes

Public Member Functions

Friends

Detailed Description

template<class T> class casa::Array< T >

To Do

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Thrown Exceptions

Friends And Related Function Documentation

Member Data Documentation

template<class T>
class casa::Array< T >