public final class MatlabNumericArray extends Object
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.
IllegalStateException
being thrown.
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).
MatlabNumericArray
is
constructed from Java arrays, the arrays provided may be jagged; see the
main constructor
for details.
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.
array(3,4,7,2)
, then in
Java to retrieve the same entry the indexing would be performed as array[2][3][6][1]
.
Modifier and Type | Class and Description |
---|---|
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 and Description |
---|
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.
|
Modifier and Type | Method and Description |
---|---|
int |
getDimensions()
The number of dimensions this array has.
|
<T> T |
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.
|
<T> T |
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. |
String |
toString()
Returns a brief description of this array.
|
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 realNullPointerException
public MatlabNumericArray(double[][] real, double[][] imaginary)
new MatlabNumericArray(DoubleArrayType.DIM_2, real, imaginary)
.real
- imaginary
- NullPointerException
public MatlabNumericArray(double[][][] real, double[][][] imaginary)
new MatlabNumericArray(DoubleArrayType.DIM_3, real, imaginary)
.real
- imaginary
- NullPointerException
public MatlabNumericArray(double[][][][] real, double[][][][] imaginary)
new MatlabNumericArray(DoubleArrayType.DIM_4, real, imaginary)
.real
- imaginary
- NullPointerException
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
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
ArrayIndexOutOfBoundsException
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 dimensionsIndexOutOfBoundsException
- 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 dimensionsIndexOutOfBoundsException
- if the indices are out of boundIllegalStateException
- 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
IllegalStateException
- if the array is realpublic double[][] getImaginaryArray2D()
getImaginaryArray(DoubleArrayType.DIM_2)
.MatlabNumericArray.ArrayDimensionException
- if the array is not a two dimensional arrayIllegalStateException
- if the array is realpublic double[][][] getImaginaryArray3D()
getImaginaryArray(DoubleArrayType.DIM_3)
.MatlabNumericArray.ArrayDimensionException
- if the array is not a three dimensional arrayIllegalStateException
- if the array is realpublic double[][][][] getImaginaryArray4D()
getImaginaryArray(DoubleArrayType.DIM_4)
.MatlabNumericArray.ArrayDimensionException
- if the array is not a four dimensional arrayIllegalStateException
- if the array is realpublic boolean isReal()
true
if the array has no imaginary values, false
otherwise. Equivalent to the MATLAB
isreal
function.