|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectucar.ma2.Array
public abstract class Array
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 composition 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.
Index
,
IndexIterator
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(DataType dtype,
int[] shape,
java.nio.ByteBuffer bb)
Create an Array from a ByteBuffer |
static Array |
factory(DataType dataType,
int[] shape,
java.lang.Object storage)
/** Generate new Array with given type, shape, 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 always 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 boolean |
getBoolean(int elem)
|
abstract byte |
getByte(Index ima)
Get the array element at the current element of ima, as a byte. |
abstract byte |
getByte(int elem)
|
abstract char |
getChar(Index ima)
Get the array element at the current element of ima, as a char. |
abstract char |
getChar(int elem)
|
java.nio.ByteBuffer |
getDataAsByteBuffer()
This gets the data as a ByteBuffer, in correct order. |
abstract double |
getDouble(Index ima)
Get the array element at the current element of ima, as a double. |
abstract double |
getDouble(int elem)
|
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. |
abstract float |
getFloat(int elem)
|
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()
Deprecated. use getIndexIterator |
Index |
getIndexPrivate()
Get an Index object used for indexed access of this Array. |
abstract int |
getInt(Index ima)
Get the array element at the current element of ima, as a int. |
abstract int |
getInt(int elem)
|
abstract long |
getLong(Index ima)
Get the array element at the current element of ima, as a long. |
abstract long |
getLong(int elem)
|
abstract java.lang.Object |
getObject(Index ima)
Get the array element at index as an Object. |
abstract java.lang.Object |
getObject(int elem)
|
IndexIterator |
getRangeIterator(java.util.List<Range> 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. |
abstract short |
getShort(int elem)
|
long |
getSize()
Get the total number of elements in the array. |
long |
getSizeBytes()
Get the total number of bytes in the array. |
abstract java.lang.Object |
getStorage()
Get underlying primitive array storage. |
boolean |
hasNext()
Check if more elements in the local iterator. |
boolean |
isUnsigned()
Find whether the underlying data should be interprested as unsigned. |
static Array |
makeArray(DataType dtype,
int npts,
double start,
double incr)
Make a 1D array from a start and inccr. |
static Array |
makeArray(DataType dtype,
java.util.List<java.lang.String> stringValues)
Make an 1D array from a list of strings. |
static Array |
makeArray(DataType dtype,
java.lang.String[] stringValues)
Make an 1D array from an array of strings. |
java.lang.Object |
next()
Return the next object in the local iterator. |
boolean |
nextBoolean()
Return the next boolean in the local iterator. |
byte |
nextByte()
Return the next byte in the local iterator. |
char |
nextChar()
Return the next char in the local iterator. |
double |
nextDouble()
Return the next double in the local iterator. |
float |
nextFloat()
Return the next float in the local iterator. |
int |
nextInt()
Return the next int in the local iterator. |
long |
nextLong()
Return the next long in the local iterator. |
short |
nextShort()
Return the next short in the local iterator. |
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. |
void |
resetLocalIterator()
Reset the local iterator. |
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<Range> 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<Range> 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 |
setBoolean(int elem,
boolean value)
|
abstract void |
setByte(Index ima,
byte value)
Set the array element at the current element of ima. |
abstract void |
setByte(int elem,
byte value)
|
abstract void |
setChar(Index ima,
char value)
Set the array element at the current element of ima. |
abstract void |
setChar(int elem,
char value)
|
abstract void |
setDouble(Index ima,
double value)
Set the array element at the current element of ima. |
abstract void |
setDouble(int elem,
double val)
|
abstract void |
setFloat(Index ima,
float value)
Set the array element at the current element of ima. |
abstract void |
setFloat(int elem,
float val)
|
abstract void |
setInt(Index ima,
int value)
Set the array element at the current element of ima. |
abstract void |
setInt(int elem,
int value)
|
abstract void |
setLong(Index ima,
long value)
Set the array element at the current element of ima. |
abstract void |
setLong(int elem,
long value)
|
abstract void |
setObject(Index ima,
java.lang.Object value)
Set the array element at index to the specified value. |
abstract void |
setObject(int elem,
java.lang.Object value)
|
abstract void |
setShort(Index ima,
short value)
Set the array element at the current element of ima. |
abstract void |
setShort(int elem,
short value)
|
void |
setUnsigned(boolean unsigned)
|
java.lang.String |
shapeToString()
Create a string representation of the shape of this Array. |
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 |
Method Detail |
---|
public static Array factory(DataType dataType, int[] shape)
dataType
- instance of DataType.shape
- shape of the array.
public static Array factory(java.lang.Class classType, int[] shape)
classType
- element Class type, eg double.class.shape
- shape of the array.
public static Array factory(DataType dataType, int[] shape, java.lang.Object storage)
dataType
- DataType, eg DataType.DOUBLE.shape
- shape of the array.storage
- primitive array of correct type
public static Array factory(java.lang.Class classType, int[] shape, java.lang.Object storage)
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 shapestorage
- 1D java array of type classType, except object types like Double.class are mapped to
their corresponding primitive type, eg double.class.
java.lang.IllegalArgumentException
- storage.length != product of shapes
java.lang.ClassCastException
- wrong storage typepublic static Array factoryConstant(java.lang.Class classType, int[] shape, java.lang.Object storage)
classType
- element Class type, eg double.class.shape
- shape of the array.storage
- primitive array of correct type of length 1
public static Array factory(java.lang.Object javaArray)
javaArray
- scalar Object or a java array of any rank and type
public static void arraycopy(Array arraySrc, int srcPos, Array arrayDst, int dstPos, int len)
arraySrc
- copy from here : if not in canonical order, an extra copy will be donesrcPos
- starting atarrayDst
- copy to here : must be in canonical orderdstPos
- starting atlen
- number of elements to copypublic static Array makeArray(DataType dtype, int npts, double start, double incr)
dtype
- data type of result. must be convertible to double.npts
- number of pointsstart
- starting valuesincr
- increment
public static Array makeArray(DataType dtype, java.util.List<java.lang.String> stringValues) throws java.lang.NumberFormatException
dtype
- data type of the array.stringValues
- list of strings.
java.lang.NumberFormatException
- if string values not parssable to specified data typepublic static Array makeArray(DataType dtype, java.lang.String[] stringValues) throws java.lang.NumberFormatException
dtype
- data type of the array.stringValues
- list of strings.
java.lang.NumberFormatException
- if string values not parssable to specified data typepublic Index getIndex()
Index
public Index getIndexPrivate()
public IndexIterator getIndexIterator()
IndexIterator
public int getRank()
public int[] getShape()
public long getSize()
public long getSizeBytes()
public IndexIterator getRangeIterator(java.util.List<Range> ranges) throws InvalidRangeException
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.
InvalidRangeException
- if ranges is invalidpublic IndexIterator getIndexIteratorFast()
public abstract java.lang.Class getElementType()
public abstract java.lang.Object getStorage()
public Array section(java.util.List<Range> ranges) throws InvalidRangeException
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.
InvalidRangeException
- if ranges is invalidpublic Array section(int[] origin, int[] shape) throws InvalidRangeException
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.
InvalidRangeException
- if ranges is invalidpublic Array section(int[] origin, int[] shape, int[] stride) throws InvalidRangeException
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.
InvalidRangeException
- if ranges is invalidpublic Array sectionNoReduce(java.util.List<Range> ranges) throws InvalidRangeException
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.
InvalidRangeException
- if ranges is invalidpublic Array sectionNoReduce(int[] origin, int[] shape, int[] stride) throws InvalidRangeException
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.
InvalidRangeException
- if ranges is invalidpublic Array slice(int dim, int value)
dim
- which dimension to fixvalue
- at what index value
public Array copy()
public java.lang.Object get1DJavaArray(java.lang.Class wantType)
wantType
- returned object will be an array of this type. This must be convertible to it.
public java.nio.ByteBuffer getDataAsByteBuffer()
public static Array factory(DataType dtype, int[] shape, java.nio.ByteBuffer bb)
dtype
- type of datashape
- shape of databb
- data is in here
public java.lang.Object copyTo1DJavaArray()
public java.lang.Object copyToNDJavaArray()
public Array flip(int dim)
dim
- dimension to flip
public Array transpose(int dim1, int dim2)
dim1
- transpose these two indicesdim2
- transpose these two indices
public Array permute(int[] dims)
dims
- the old index dims[k] becomes the new kth index.
IllegalArgumentException:
- wrong rank or dim[k] not validpublic Array reshape(int[] shape)
shape
- the new shape
java.lang.IllegalArgumentException
- a and b are not conformablepublic Array reduce()
public Array reduce(int dim)
dim
- dimension to eliminate: must be of length one, else IllegalArgumentException
public boolean isUnsigned()
public void setUnsigned(boolean unsigned)
public abstract double getDouble(Index ima)
ima
- Index with current element set
index
cast to double if necessary.public abstract void setDouble(Index ima, double value)
ima
- Index with current element setvalue
- the new value; cast to underlying data type if necessary.public abstract float getFloat(Index ima)
ima
- Index with current element set
index
cast to float if necessary.public abstract void setFloat(Index ima, float value)
ima
- Index with current element setvalue
- the new value; cast to underlying data type if necessary.public abstract long getLong(Index ima)
ima
- Index with current element set
index
cast to long if necessary.public abstract void setLong(Index ima, long value)
ima
- Index with current element setvalue
- the new value; cast to underlying data type if necessary.public abstract int getInt(Index ima)
ima
- Index with current element set
index
cast to int if necessary.public abstract void setInt(Index ima, int value)
ima
- Index with current element setvalue
- the new value; cast to underlying data type if necessary.public abstract short getShort(Index ima)
ima
- Index with current element set
index
cast to short if necessary.public abstract void setShort(Index ima, short value)
ima
- Index with current element setvalue
- the new value; cast to underlying data type if necessary.public abstract byte getByte(Index ima)
ima
- Index with current element set
index
cast to float if necessary.public abstract void setByte(Index ima, byte value)
ima
- Index with current element setvalue
- the new value; cast to underlying data type if necessary.public abstract char getChar(Index ima)
ima
- Index with current element set
index
cast to char if necessary.public abstract void setChar(Index ima, char value)
ima
- Index with current element setvalue
- the new value; cast to underlying data type if necessary.public abstract boolean getBoolean(Index ima)
ima
- Index with current element set
index
cast to boolean if necessary.
ForbiddenConversionException
- if underlying array not booleanpublic abstract void setBoolean(Index ima, boolean value)
ima
- Index with current element setvalue
- the new value; cast to underlying data type if necessary.
ForbiddenConversionException
- if underlying array not booleanpublic abstract java.lang.Object getObject(Index ima)
ima
- element Index
index
java.lang.ArrayIndexOutOfBoundsException
- if index incorrect rank or out of boundspublic abstract void setObject(Index ima, java.lang.Object value)
ima
- Index with current element setvalue
- the new value.
java.lang.ArrayIndexOutOfBoundsException
- if index incorrect rank or out of bounds
java.lang.ClassCastException
- if Object is incorrect typepublic abstract double getDouble(int elem)
public abstract void setDouble(int elem, double val)
public abstract float getFloat(int elem)
public abstract void setFloat(int elem, float val)
public abstract long getLong(int elem)
public abstract void setLong(int elem, long value)
public abstract int getInt(int elem)
public abstract void setInt(int elem, int value)
public abstract short getShort(int elem)
public abstract void setShort(int elem, short value)
public abstract byte getByte(int elem)
public abstract void setByte(int elem, byte value)
public abstract char getChar(int elem)
public abstract void setChar(int elem, char value)
public abstract boolean getBoolean(int elem)
public abstract void setBoolean(int elem, boolean value)
public abstract java.lang.Object getObject(int elem)
public abstract void setObject(int elem, java.lang.Object value)
public java.lang.String toString()
toString
in class java.lang.Object
public java.lang.String shapeToString()
public boolean hasNext()
arr.resetLocalIterator(); while (arr.hasNext()) { double val = mdata.nextDouble(); .. } <.pre>
public java.lang.Object next()
public double nextDouble()
public float nextFloat()
public byte nextByte()
public short nextShort()
public int nextInt()
public long nextLong()
public char nextChar()
public boolean nextBoolean()
public void resetLocalIterator()
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |