ucar.ma2
Class Array

java.lang.Object
  ucar.ma2.Array

Direct Known Subclasses:

ArrayBoolean, ArrayByte, ArrayChar, ArrayDouble, ArrayFloat, ArrayInt, ArrayLong, ArrayObject, ArrayShort, ArrayStructure

public abstract class Array
extends java.lang.Object

Superclass for implementations of multidimensional arrays. An Array has a classType which gives the Class of its elements, and a shape which describes the number of elements in each index. The rank is the number of indices. A scalar Array has rank = 0. An Array may have arbitrary rank. The Array size is the total number of elements, which must be less than 2^31 (about 2x10^9).

Actual data storage is done with Java 1D arrays and stride index calculations. This makes our Arrays rectangular, i.e. no "ragged arrays" where different elements can have different lengths as in Java multidimensional arrays, which are arrays of arrays.

Each primitive Java type (boolean, byte, char, short, int, long, float, double) has a corresponding concrete implementation, e.g. ArrayBoolean, ArrayDouble. Reference types are all implemented using the ArrayObject class, with the exceptions of the reference types that correspond to the primitive types, eg Double.class is mapped to double.class.

For efficiency, each Array type implementation has concrete subclasses for ranks 0-7, eg ArrayDouble.D0 is a double array of rank 0, ArrayDouble.D1 is a double array of rank 1, etc. These type and rank specific classes are convenient to work with when you know the type and rank of the Array. Ranks greater than 7 are handled by the type-specific superclass e.g. ArrayDouble. The Array class itself is used for fully general handling of any type and rank array. Use the Array.factory() methods to create Arrays in a general way.

The stride index calculations allow logical views to be efficiently implemented, eg subset, transpose, slice, etc. These views use the same data storage as the original Array they are derived from. The index stride calculations are equally efficient for any chain of logical views.

The type, shape and backing storage of an Array are immutable. The data itself is read or written using an Index or an IndexIterator, which stores any needed state information for efficient traversal. This makes use of Arrays thread-safe (as long as you dont share the Index or IndexIterator) except for the possibility of non-atomic read/write on long/doubles. If this is the case, you should probably synchronize your calls. Presumably 64-bit CPUs will make those operations atomic also.

Version:

$Revision:51 $ $Date:2006-07-12 17:13:13Z $

Author:

caron

See Also:

Index, IndexIterator

Field Summary

static Index

scalarIndex

Method Summary

static void	arraycopy(Array arraySrc, int srcPos, Array arrayDst, int dstPos, int len) Cover for System.arraycopy().
Array	copy() Create a copy of this Array, copying the data so that physical order is the same as logical order
java.lang.Object	copyTo1DJavaArray() Copy this array to a 1D Java primitive array of type getElementType(), with the physical order of the result the same as logical order.
java.lang.Object	copyToNDJavaArray() Copy this array to a n-Dimensioanl Java primitive array of type getElementType() and rank getRank().
static Array	factory(java.lang.Class classType, int[] shape) Generate new Array with given type and shape and zeroed storage.
static Array	factory(java.lang.Class classType, int[] shape, java.lang.Object storage) Generate new Array with given type, shape, storage.
static Array	factory(DataType dataType, int[] shape) Generate new Array with given type and shape and zeroed storage.
static Array	factory(java.lang.Object javaArray) Generate a new Array from a java array of any rank and type.
static Array	factoryConstant(java.lang.Class classType, int[] shape, java.lang.Object storage) Generate new Array with given type and shape and an Index that allways return 0.
Array	flip(int dim) Create a new Array using same backing store as this Array, by flipping the index so that it runs from shape[index]-1 to 0.
java.lang.Object	get1DJavaArray(java.lang.Class wantType) This gets the equivilent java array of the wanted type, in correct order.
abstract boolean	getBoolean(Index ima) Get the array element at the current element of ima, as a boolean.
abstract byte	getByte(Index ima) Get the array element at the current element of ima, as a byte.
abstract char	getChar(Index ima) Get the array element at the current element of ima, as a char.
abstract double	getDouble(Index ima) Get the array element at the current element of ima, as a double.
abstract java.lang.Class	getElementType() Get the element class type of this Array
abstract float	getFloat(Index ima) Get the array element at the current element of ima, as a float.
Index	getIndex() Get an Index object used for indexed access of this Array.
IndexIterator	getIndexIterator() Get an index iterator for traversing the array in canonical order.
IndexIterator	getIndexIteratorFast() Do not use this unless you have complete control over the Array.
java.lang.String	getIndexName(int dim) Get the name of one of the indices.
abstract int	getInt(Index ima) Get the array element at the current element of ima, as a int.
abstract long	getLong(Index ima) Get the array element at the current element of ima, as a long.
abstract java.lang.Object	getObject(Index ima) Get the array element at index as an Object.
IndexIterator	getRangeIterator(java.util.List ranges) Get an index iterator for traversing a section of the array in canonical order.
int	getRank() Get the number of dimensions of the array.
int[]	getShape() Get the shape: length of array in each dimension.
abstract short	getShort(Index ima) Get the array element at the current element of ima, as a short.
long	getSize() Get the total number of elements in the array.
abstract java.lang.Object	getStorage() Get underlying primitive array storage.
Array	permute(int[] dims) Create a new Array using same backing store as this Array, by permuting the indices.
Array	reduce() Create a new Array using same backing store as this Array, by eliminating any dimensions with length one.
Array	reduce(int dim) Create a new Array using same backing store as this Array, by eliminating the specified dimension.
Array	reshape(int[] shape) Create a new Array by copying this Array to a new one with given shape
Array	section(int[] origin, int[] shape) Create a new Array as a subsection of this Array, with rank reduction.
Array	section(int[] origin, int[] shape, int[] stride) Create a new Array as a subsection of this Array, with rank reduction.
Array	section(java.util.List ranges) Create a new Array as a subsection of this Array, with rank reduction.
Array	sectionNoReduce(int[] origin, int[] shape, int[] stride) Create a new Array as a subsection of this Array, without rank reduction.
Array	sectionNoReduce(java.util.List ranges) Create a new Array as a subsection of this Array, without rank reduction.
abstract void	setBoolean(Index ima, boolean value) Set the array element at the current element of ima.
abstract void	setByte(Index ima, byte value) Set the array element at the current element of ima.
abstract void	setChar(Index ima, char value) Set the array element at the current element of ima.
abstract void	setDouble(Index ima, double value) Set the array element at the current element of ima.
abstract void	setFloat(Index ima, float value) Set the array element at the current element of ima.
void	setIndexName(int dim, java.lang.String indexName) Set the name of one of the indices.
abstract void	setInt(Index ima, int value) Set the array element at the current element of ima.
abstract void	setLong(Index ima, long value) Set the array element at the current element of ima.
abstract void	setObject(Index ima, java.lang.Object value) Set the array element at index to the specified value.
abstract void	setShort(Index ima, short value) Set the array element at the current element of ima.
java.lang.String	shapeToString()
Array	slice(int dim, int value) Create a new Array using same backing store as this Array, by fixing the specified dimension at the specified index value.
java.lang.String	toString()
Array	transpose(int dim1, int dim2) Create a new Array using same backing store as this Array, by transposing two of the indices.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

scalarIndex

public static Index scalarIndex

Method Detail

factory

public static Array factory(DataType dataType,
                            int[] shape)

Generate new Array with given type and shape and zeroed storage.

Parameters:

dataType - instance of DataType.

shape - shape of the array.

Returns:

new Array or Array.D if 0 <= rank <= 7.

factory

public static Array factory(java.lang.Class classType,
                            int[] shape)

Generate new Array with given type and shape and zeroed storage.

Parameters:

classType - element Class type, eg double.class.

shape - shape of the array.

Returns:

new Array or Array.D if 0 <= rank <= 7.

factoryConstant

public static Array factoryConstant(java.lang.Class classType,
                                    int[] shape,
                                    java.lang.Object storage)

Generate new Array with given type and shape and an Index that allways return 0.

Parameters:

classType - element Class type, eg double.class.

shape - shape of the array.

storage - primitive array of correct type of length 1

Returns:

new Array or Array.D if 0 <= rank <= 7.

factory

public static Array factory(java.lang.Class classType,
                            int[] shape,
                            java.lang.Object storage)

Generate new Array with given type, shape, storage. This should be package private, but is exposed for efficiency. Normally use factory( Class classType, int [] shape) instead. storage must be 1D array of type classType. storage.length must equal product of shapes storage data needs to be in canonical order

Parameters:

classType - element class type, eg double.class. Corresponding Object types like Double.class are mapped to double.class. Any reference types use ArrayObject.

shape - array shape

storage - 1D java array of type classType, except object types like Double.class are mapped to their corresponding primitive type, eg double.class. So the primitive

Throws:

java.lang.IllegalArgumentException - storage.length != product of shapes

java.lang.ClassCastException - wrong storage type

factory

public static Array factory(java.lang.Object javaArray)

Generate a new Array from a java array of any rank and type. This makes a COPY of the data values of javaArray. LOOK: not sure this works for reference types.

Parameters:

javaArray - scalar Object or a java array of any rank and type

Returns:

Array of the appropriate rank and type, with the data copied from javaArray.

arraycopy

public static void arraycopy(Array arraySrc,
                             int srcPos,
                             Array arrayDst,
                             int dstPos,
                             int len)

Cover for System.arraycopy(). Works with the underlying data arrays. Exposed for efficiency; use at your own risk. LOOK: not sure this works for reference types.

Parameters:

arraySrc - copy from here

srcPos - starting at

arrayDst - copy to here

dstPos - starting at

len - number of elements to copy

getIndex

public Index getIndex()

Get an Index object used for indexed access of this Array.

See Also:

Index

getIndexIterator

public IndexIterator getIndexIterator()

Get an index iterator for traversing the array in canonical order.

See Also:

IndexIterator

getRank

public int getRank()

Get the number of dimensions of the array.

Returns:

number of dimensions of the array

getShape

public int[] getShape()

Get the shape: length of array in each dimension.

Returns:

array whose length is the rank of this Array and whose elements represent the length of each of its indices.

getSize

public long getSize()

Get the total number of elements in the array.

Returns:

total number of elements in the array

getRangeIterator

public IndexIterator getRangeIterator(java.util.List ranges)
                               throws InvalidRangeException

Get an index iterator for traversing a section of the array in canonical order. This is equivalent to Array.section(ranges).getIterator();

Parameters:

ranges - list of Ranges that specify the array subset. Must be same rank as original Array. A particular Range: 1) may be a subset, or 2) may be null, meaning use entire Range.

Returns:

an IndexIterator over the named range.

Throws:

InvalidRangeException

getIndexIteratorFast

public IndexIterator getIndexIteratorFast()

Do not use this unless you have complete control over the Array. Use getIndexIterator(), which will return a fast iterator if possible.

See Also:

getIndexIterator()

getElementType

public abstract java.lang.Class getElementType()

Get the element class type of this Array

getStorage

public abstract java.lang.Object getStorage()

Get underlying primitive array storage. Exposed for efficiency, use at your own risk.

section

public Array section(java.util.List ranges)
              throws InvalidRangeException

Create a new Array as a subsection of this Array, with rank reduction. No data is moved, so the new Array references the same backing store as the original.

Parameters:

ranges - list of Ranges that specify the array subset. Must be same rank as original Array. A particular Range: 1) may be a subset, or 2) may be null, meaning use entire Range. If Range[dim].length == 1, then the rank of the resulting Array is reduced at that dimension.

Returns:

the new Array

Throws:

InvalidRangeException

section

public Array section(int[] origin,
                     int[] shape)
              throws InvalidRangeException

Create a new Array as a subsection of this Array, with rank reduction. No data is moved, so the new Array references the same backing store as the original.

Parameters:

origin - int array specifying the starting index. Must be same rank as original Array.

shape - int array specifying the extents in each dimension. This becomes the shape of the returned Array. Must be same rank as original Array. If shape[dim] == 1, then the rank of the resulting Array is reduced at that dimension.

Returns:

the new Array

Throws:

InvalidRangeException

section

public Array section(int[] origin,
                     int[] shape,
                     int[] stride)
              throws InvalidRangeException

Create a new Array as a subsection of this Array, with rank reduction. No data is moved, so the new Array references the same backing store as the original.

Parameters:

origin - int array specifying the starting index. Must be same rank as original Array.

shape - int array specifying the extents in each dimension. This becomes the shape of the returned Array. Must be same rank as original Array. If shape[dim] == 1, then the rank of the resulting Array is reduced at that dimension.

stride - int array specifying the strides in each dimension. If null, assume all ones.

Returns:

the new Array

Throws:

InvalidRangeException

sectionNoReduce

public Array sectionNoReduce(java.util.List ranges)
                      throws InvalidRangeException

Create a new Array as a subsection of this Array, without rank reduction. No data is moved, so the new Array references the same backing store as the original.

Parameters:

ranges - list of Ranges that specify the array subset. Must be same rank as original Array. A particular Range: 1) may be a subset, or 2) may be null, meaning use entire Range.

Returns:

the new Array

Throws:

InvalidRangeException

sectionNoReduce

public Array sectionNoReduce(int[] origin,
                             int[] shape,
                             int[] stride)
                      throws InvalidRangeException

Create a new Array as a subsection of this Array, without rank reduction. No data is moved, so the new Array references the same backing store as the original.

Parameters:

origin - int array specifying the starting index. Must be same rank as original Array.

shape - int array specifying the extents in each dimension. This becomes the shape of the returned Array. Must be same rank as original Array.

stride - int array specifying the strides in each dimension. If null, assume all ones.

Returns:

the new Array

Throws:

InvalidRangeException

slice

public Array slice(int dim,
                   int value)

Create a new Array using same backing store as this Array, by fixing the specified dimension at the specified index value. This reduces rank by 1.

Parameters:

dim - which dimension to fix

value - at what index value

Returns:

a new Array

copy

public Array copy()

Create a copy of this Array, copying the data so that physical order is the same as logical order

Returns:

the new Array

get1DJavaArray

public java.lang.Object get1DJavaArray(java.lang.Class wantType)

This gets the equivilent java array of the wanted type, in correct order. It avoids copying if possible.

Parameters:

wantType - returned object will be an array of this type. This must be convertible to it.

Returns:

copyTo1DJavaArray

copyTo1DJavaArray

public java.lang.Object copyTo1DJavaArray()

Copy this array to a 1D Java primitive array of type getElementType(), with the physical order of the result the same as logical order.

Returns:

a Java 1D array of type getElementType().

copyToNDJavaArray

public java.lang.Object copyToNDJavaArray()

Copy this array to a n-Dimensioanl Java primitive array of type getElementType() and rank getRank(). Makes a copy of the data.

Returns:

a Java ND array of type getElementType().

flip

public Array flip(int dim)

Create a new Array using same backing store as this Array, by flipping the index so that it runs from shape[index]-1 to 0.

Parameters:

dim - dimension to flip

Returns:

the new Array

transpose

public Array transpose(int dim1,
                       int dim2)

Create a new Array using same backing store as this Array, by transposing two of the indices.

Parameters:

dim1 - transpose these two indices

dim2 - transpose these two indices

Returns:

the new Array

permute

public Array permute(int[] dims)

Create a new Array using same backing store as this Array, by permuting the indices.

Parameters:

dims - the old index dims[k] becomes the new kth index.

Returns:

the new Array

Throws:

IllegalArgumentException: - wrong rank or dim[k] not valid

reshape

public Array reshape(int[] shape)

Create a new Array by copying this Array to a new one with given shape

Parameters:

shape - the new shape

Returns:

the new Array

Throws:

java.lang.IllegalArgumentException - a and b are not conformable

reduce

public Array reduce()

Create a new Array using same backing store as this Array, by eliminating any dimensions with length one.

Returns:

the new Array

reduce

public Array reduce(int dim)

Create a new Array using same backing store as this Array, by eliminating the specified dimension.

Parameters:

dim - dimension to eliminate: must be of length one, else IllegalArgumentException

Returns:

the new Array

setIndexName

public void setIndexName(int dim,
                         java.lang.String indexName)

Set the name of one of the indices.

Parameters:

dim - which index?

indexName - name of index

getIndexName

public java.lang.String getIndexName(int dim)

Get the name of one of the indices.

Parameters:

dim - which index?

Returns:

name of index, or null if none.

getDouble

public abstract double getDouble(Index ima)

Get the array element at the current element of ima, as a double.

Parameters:

ima - Index with current element set

Returns:

value at index cast to double if necessary.

setDouble

public abstract void setDouble(Index ima,
                               double value)

Set the array element at the current element of ima.

Parameters:

ima - Index with current element set

value - the new value; cast to underlying data type if necessary.

getFloat

public abstract float getFloat(Index ima)

Get the array element at the current element of ima, as a float.

Parameters:

ima - Index with current element set

Returns:

value at index cast to float if necessary.

setFloat

public abstract void setFloat(Index ima,
                              float value)

Set the array element at the current element of ima.

Parameters:

ima - Index with current element set

value - the new value; cast to underlying data type if necessary.

getLong

public abstract long getLong(Index ima)

Get the array element at the current element of ima, as a long.

Parameters:

ima - Index with current element set

Returns:

value at index cast to long if necessary.

setLong

public abstract void setLong(Index ima,
                             long value)

Set the array element at the current element of ima.

Parameters:

ima - Index with current element set

value - the new value; cast to underlying data type if necessary.

getInt

public abstract int getInt(Index ima)

Get the array element at the current element of ima, as a int.

Parameters:

ima - Index with current element set

Returns:

value at index cast to int if necessary.

setInt

public abstract void setInt(Index ima,
                            int value)

Set the array element at the current element of ima.

Parameters:

ima - Index with current element set

value - the new value; cast to underlying data type if necessary.

getShort

public abstract short getShort(Index ima)

Get the array element at the current element of ima, as a short.

Parameters:

ima - Index with current element set

Returns:

value at index cast to short if necessary.

setShort

public abstract void setShort(Index ima,
                              short value)

Set the array element at the current element of ima.

Parameters:

ima - Index with current element set

value - the new value; cast to underlying data type if necessary.

getByte

public abstract byte getByte(Index ima)

Get the array element at the current element of ima, as a byte.

Parameters:

ima - Index with current element set

Returns:

value at index cast to float if necessary.

setByte

public abstract void setByte(Index ima,
                             byte value)

Set the array element at the current element of ima.

Parameters:

ima - Index with current element set

value - the new value; cast to underlying data type if necessary.

getChar

public abstract char getChar(Index ima)

Get the array element at the current element of ima, as a char.

Parameters:

ima - Index with current element set

Returns:

value at index cast to char if necessary.

setChar

public abstract void setChar(Index ima,
                             char value)

Set the array element at the current element of ima.

Parameters:

ima - Index with current element set

value - the new value; cast to underlying data type if necessary.

getBoolean

public abstract boolean getBoolean(Index ima)

Get the array element at the current element of ima, as a boolean.

Parameters:

ima - Index with current element set

Returns:

value at index cast to boolean if necessary.

Throws:

ForbiddenConversionException - if underlying array not boolean

setBoolean

public abstract void setBoolean(Index ima,
                                boolean value)

Set the array element at the current element of ima.

Parameters:

ima - Index with current element set

value - the new value; cast to underlying data type if necessary.

Throws:

ForbiddenConversionException - if underlying array not boolean

getObject

public abstract java.lang.Object getObject(Index ima)

Get the array element at index as an Object. The returned value is wrapped in an object, eg Double for double

Parameters:

ima - element Index

Returns:

Object value at index

Throws:

java.lang.ArrayIndexOutOfBoundsException - if index incorrect rank or out of bounds

setObject

public abstract void setObject(Index ima,
                               java.lang.Object value)

Set the array element at index to the specified value. the value must be passed wrapped in the appropriate Object (eg Double for double)

Parameters:

ima - Index with current element set

value - the new value.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if index incorrect rank or out of bounds

java.lang.ClassCastException - if Object is incorrect type

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

shapeToString

public java.lang.String shapeToString()