|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectmatlabcontrol.extensions.MatlabNumericArray
public final class MatlabNumericArray
Acts as a MATLAB array of doubles. MATLAB arrays of any numeric type may be represented by a
MatlabNumericArray
, but precision may be lost in the process. Dimensions of 2 and greater are supported. (No
array in MATLAB has a dimension less than 2.) This representation is a copy of the MATLAB data, not a live view.
Retrieving large arrays from MATLAB can result in a OutOfMemoryError
; if this occurs you may want to either
retrieve only part of the array from MATLAB or increase your Java Virtual Machine's heap size.
Note: Sparse arrays are not supported. Attempts to retrieve a sparse may not throw an exception, but the
result will not be valid.
Both the real and imaginary components of a MATLAB array are supported. If the array has no imaginary values then
attempts to access these values will result in a IllegalStateException
being thrown.
Arrays in MATLAB are stored in a linear manner. The number and lengths of the dimensions are stored separately from
the real and imaginary value entries. Each dimension has a fixed length. (MATLAB's array implementation is known as
a dope vector.)
Java has no multidimensional array type. To support multiple dimensions, Java allows for creating arrays of any data
type, including arrays. (Java's array implementation is known as an Iliffe vector.) A two dimensional array of
double
s, double[][]
, is just an array of double[]
. A result of this is that each
double[]
can have a different length. When not all inner arrays for a given dimension have the same length,
then the array is known as as a jagged array (also known as a ragged array).
When an array is retrieved from MATLAB the resulting Java array is never jagged. When a MatlabNumericArray
is
constructed from Java arrays, the arrays provided may be jagged; see the
main constructor
for details.
Each instance knows the number of dimensions it represents and can create the corresponding multidimensional Java
array. In order to do this in a type safe manner the methods getRealArray(...)
and getImaginaryArray(...)
exist. Convenience methods exist to easily
retrieve the arrays as two, three, and four dimensional arrays. All of these methods will throw a
MatlabNumericArray.ArrayDimensionException
if the array is not actually of that dimension. It is also possible to retrieve
values from the array without converting it to the corresponding multidimensional Java array. This can be done either
by using the index into the underlying linear MATLAB array, or by using the multidimensional indices. Retrieving
values in this manner does not require the computation and memory necessary to create the multidimensional Java
array.
While this class mimics the dimension and lengths of a MATLAB array, it uses Java's 0-index convention instead of
MATLAB's 1-index convention. For instance in MATLAB if an array were indexed into as array(3,4,7,2)
, then in
Java to retrieve the same entry the indexing would be performed as array[2][3][6][1]
.
Once constructed, this class is unconditionally thread-safe. If the data provided to a constructor is modified while
construction is occurring, problems may occur.
MatlabTypeConverter.setNumericArray(java.lang.String, matlabcontrol.extensions.MatlabNumericArray)
,
MatlabTypeConverter.getNumericArray(java.lang.String)
Nested Class Summary | |
---|---|
static class |
MatlabNumericArray.ArrayDimensionException
Represents attempting to retrieve or manipulate a MATLAB array as the wrong dimension. |
static class |
MatlabNumericArray.DoubleArrayType<T>
An array type of dimension 2 or greater which holds double s. |
Constructor Summary | |
---|---|
MatlabNumericArray(double[][][][] real,
double[][][][] imaginary)
Convenience constructor, equivalent to new MatlabNumericArray(DoubleArrayType.DIM_4, real, imaginary) . |
|
MatlabNumericArray(double[][][] real,
double[][][] imaginary)
Convenience constructor, equivalent to new MatlabNumericArray(DoubleArrayType.DIM_3, real, imaginary) . |
|
MatlabNumericArray(double[][] real,
double[][] imaginary)
Convenience constructor, equivalent to new MatlabNumericArray(DoubleArrayType.DIM_2, real, imaginary) . |
|
MatlabNumericArray(MatlabNumericArray.DoubleArrayType<T> type,
T real,
T imaginary)
Constructs a numeric array from Java arrays that can be transferred to MATLAB. |
Method Summary | ||
---|---|---|
int |
getDimensions()
The number of dimensions this array has. |
|
|
getImaginaryArray(MatlabNumericArray.DoubleArrayType<T> type)
Returns a double array of type T that holds the imaginary values from the MATLAB array. |
|
double[][] |
getImaginaryArray2D()
Equivalent to getImaginaryArray(DoubleArrayType.DIM_2) . |
|
double[][][] |
getImaginaryArray3D()
Equivalent to getImaginaryArray(DoubleArrayType.DIM_3) . |
|
double[][][][] |
getImaginaryArray4D()
Equivalent to getImaginaryArray(DoubleArrayType.DIM_4) . |
|
double |
getImaginaryValue(int... indices)
Gets the imaginary value at the specified indices . |
|
double |
getImaginaryValue(int linearIndex)
Gets the imaginary value at linearIndex treating this array as the underlying one dimensional array. |
|
int |
getLength()
The length of the underlying linear array. |
|
int[] |
getLengths()
Returns the lengths of each dimension with respect to their index. |
|
|
getRealArray(MatlabNumericArray.DoubleArrayType<T> type)
Returns a double array of type T that holds the real values from the MATLAB array. |
|
double[][] |
getRealArray2D()
Equivalent to getRealArray(DoubleArrayType.DIM_2) . |
|
double[][][] |
getRealArray3D()
Equivalent to getRealArray(DoubleArrayType.DIM_3) . |
|
double[][][][] |
getRealArray4D()
Equivalent to getRealArray(DoubleArrayType.DIM_4) . |
|
double |
getRealValue(int... indices)
Gets the real value at the specified indices . |
|
double |
getRealValue(int linearIndex)
Gets the real value at linearIndex treating this array as the underlying one dimensional array. |
|
boolean |
isReal()
Returns true if the array has no imaginary values, false otherwise. |
|
java.lang.String |
toString()
Returns a brief description of this array. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Constructor Detail |
---|
public MatlabNumericArray(MatlabNumericArray.DoubleArrayType<T> type, T real, T imaginary)
imaginary
array
may be null
, if so then this array will be real. References to the arrays passed in are not kept, and
modifying the array data after this class has been constructed will have no effect. If the data is modified
concurrently with this class's construction, problems may arise.
real
and imaginary
arrays are provided then the maximum length per dimension is determined
across both arrays. For parts of the array that have a length less than the maximum length, 0
will be
used.
T
- type
- may not be null
real
- may not be null
imaginary
- may be null
, if null
then this array will be real
java.lang.NullPointerException
public MatlabNumericArray(double[][] real, double[][] imaginary)
new MatlabNumericArray(DoubleArrayType.DIM_2, real, imaginary)
.
real
- imaginary
-
java.lang.NullPointerException
public MatlabNumericArray(double[][][] real, double[][][] imaginary)
new MatlabNumericArray(DoubleArrayType.DIM_3, real, imaginary)
.
real
- imaginary
-
java.lang.NullPointerException
public MatlabNumericArray(double[][][][] real, double[][][][] imaginary)
new MatlabNumericArray(DoubleArrayType.DIM_4, real, imaginary)
.
real
- imaginary
-
java.lang.NullPointerException
Method Detail |
---|
public double getRealValue(int linearIndex)
linearIndex
treating this array as the underlying one dimensional array. This
is equivalent to indexing into a MATLAB array with just one subscript.
linearIndex
-
linearIndex
java.lang.ArrayIndexOutOfBoundsException
public double getImaginaryValue(int linearIndex)
linearIndex
treating this array as the underlying one dimensional array.
This is equivalent to indexing into a MATLAB array with just one subscript.
linearIndex
-
linearIndex
java.lang.ArrayIndexOutOfBoundsException
java.lang.IllegalStateException
- if the array is realpublic double getRealValue(int... indices)
indices
. The amount of indices provided must be the number of
dimensions in the array.
indices
-
indices
MatlabNumericArray.ArrayDimensionException
- if number of indices is not the number of dimensions
java.lang.IndexOutOfBoundsException
- if the indices are out of boundpublic double getImaginaryValue(int... indices)
indices
. The amount of indices provided must be the number of
dimensions in the array.
indices
-
indices
MatlabNumericArray.ArrayDimensionException
- if number of indices is not the number of dimensions
java.lang.IndexOutOfBoundsException
- if the indices are out of bound
java.lang.IllegalStateException
- if the array is realpublic int getDimensions()
public int[] getLengths()
getDimensions()
.
public int getLength()
public <T> T getRealArray(MatlabNumericArray.DoubleArrayType<T> type)
double
array of type T
that holds the real values from the MATLAB array.
T
- type
-
MatlabNumericArray.ArrayDimensionException
- if the array is not of the dimension specified by type
public double[][] getRealArray2D()
getRealArray(DoubleArrayType.DIM_2)
.
MatlabNumericArray.ArrayDimensionException
- if the array is not a two dimensional arraypublic double[][][] getRealArray3D()
getRealArray(DoubleArrayType.DIM_3)
.
MatlabNumericArray.ArrayDimensionException
- if the array is not a three dimensional arraypublic double[][][][] getRealArray4D()
getRealArray(DoubleArrayType.DIM_4)
.
MatlabNumericArray.ArrayDimensionException
- if the array is not a four dimensional arraypublic <T> T getImaginaryArray(MatlabNumericArray.DoubleArrayType<T> type)
double
array of type T
that holds the imaginary values from the MATLAB array.
T
- type
-
MatlabNumericArray.ArrayDimensionException
- if the array is not of the dimension specified by type
java.lang.IllegalStateException
- if the array is realpublic double[][] getImaginaryArray2D()
getImaginaryArray(DoubleArrayType.DIM_2)
.
MatlabNumericArray.ArrayDimensionException
- if the array is not a two dimensional array
java.lang.IllegalStateException
- if the array is realpublic double[][][] getImaginaryArray3D()
getImaginaryArray(DoubleArrayType.DIM_3)
.
MatlabNumericArray.ArrayDimensionException
- if the array is not a three dimensional array
java.lang.IllegalStateException
- if the array is realpublic double[][][][] getImaginaryArray4D()
getImaginaryArray(DoubleArrayType.DIM_4)
.
MatlabNumericArray.ArrayDimensionException
- if the array is not a four dimensional array
java.lang.IllegalStateException
- if the array is realpublic boolean isReal()
true
if the array has no imaginary values, false
otherwise. Equivalent to the MATLAB
isreal
function.
public java.lang.String toString()
toString
in class java.lang.Object
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |