|
||||||||||
| 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
doubles, 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 doubles. |
| 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 nullreal - may not be nullimaginary - 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.ArrayIndexOutOfBoundsExceptionpublic 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 typepublic 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 | |||||||||