matlabcontrol.extensions
Class MatlabNumericArray

java.lang.Object
  extended by matlabcontrol.extensions.MatlabNumericArray

public final class MatlabNumericArray
extends java.lang.Object

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.

Since:
4.0.0
See Also:
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.
<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.
 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

MatlabNumericArray

public MatlabNumericArray(MatlabNumericArray.DoubleArrayType<T> type,
                          T real,
                          T imaginary)
Constructs a numeric array from Java arrays that can be transferred to MATLAB. The 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.

The arrays may be jagged; however, MATLAB does not support jagged arrays and therefore the arrays will be treated as if they had uniform length for each dimension. For each dimension the maximum length is determined. If both the 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.

Type Parameters:
T -
Parameters:
type - may not be null
real - may not be null
imaginary - may be null, if null then this array will be real
Throws:
java.lang.NullPointerException

MatlabNumericArray

public MatlabNumericArray(double[][] real,
                          double[][] imaginary)
Convenience constructor, equivalent to new MatlabNumericArray(DoubleArrayType.DIM_2, real, imaginary).

Parameters:
real -
imaginary -
Throws:
java.lang.NullPointerException

MatlabNumericArray

public MatlabNumericArray(double[][][] real,
                          double[][][] imaginary)
Convenience constructor, equivalent to new MatlabNumericArray(DoubleArrayType.DIM_3, real, imaginary).

Parameters:
real -
imaginary -
Throws:
java.lang.NullPointerException

MatlabNumericArray

public MatlabNumericArray(double[][][][] real,
                          double[][][][] imaginary)
Convenience constructor, equivalent to new MatlabNumericArray(DoubleArrayType.DIM_4, real, imaginary).

Parameters:
real -
imaginary -
Throws:
java.lang.NullPointerException
Method Detail

getRealValue

public double getRealValue(int linearIndex)
Gets the real value at linearIndex treating this array as the underlying one dimensional array. This is equivalent to indexing into a MATLAB array with just one subscript.

Parameters:
linearIndex -
Returns:
real value at linearIndex
Throws:
java.lang.ArrayIndexOutOfBoundsException

getImaginaryValue

public double getImaginaryValue(int linearIndex)
Gets the imaginary value at linearIndex treating this array as the underlying one dimensional array. This is equivalent to indexing into a MATLAB array with just one subscript.

Parameters:
linearIndex -
Returns:
imaginary value at linearIndex
Throws:
java.lang.ArrayIndexOutOfBoundsException
java.lang.IllegalStateException - if the array is real

getRealValue

public double getRealValue(int... indices)
Gets the real value at the specified indices. The amount of indices provided must be the number of dimensions in the array.

Parameters:
indices -
Returns:
real value at indices
Throws:
MatlabNumericArray.ArrayDimensionException - if number of indices is not the number of dimensions
java.lang.IndexOutOfBoundsException - if the indices are out of bound

getImaginaryValue

public double getImaginaryValue(int... indices)
Gets the imaginary value at the specified indices. The amount of indices provided must be the number of dimensions in the array.

Parameters:
indices -
Returns:
imaginary value at indices
Throws:
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 real

getDimensions

public int getDimensions()
The number of dimensions this array has.

Returns:
number of dimensions

getLengths

public int[] getLengths()
Returns the lengths of each dimension with respect to their index. In MATLAB the first dimension (0 index in the returned integer array) is the row length. The second dimension is the column length. The third dimension and beyond are pages. The length of the returned array will be the number of dimensions returned by getDimensions().

Returns:
lengths

getLength

public int getLength()
The length of the underlying linear array.

Returns:
length

getRealArray

public <T> T getRealArray(MatlabNumericArray.DoubleArrayType<T> type)
Returns a double array of type T that holds the real values from the MATLAB array.

Type Parameters:
T -
Parameters:
type -
Returns:
Throws:
MatlabNumericArray.ArrayDimensionException - if the array is not of the dimension specified by type

getRealArray2D

public double[][] getRealArray2D()
Equivalent to getRealArray(DoubleArrayType.DIM_2).

Returns:
Throws:
MatlabNumericArray.ArrayDimensionException - if the array is not a two dimensional array

getRealArray3D

public double[][][] getRealArray3D()
Equivalent to getRealArray(DoubleArrayType.DIM_3).

Returns:
Throws:
MatlabNumericArray.ArrayDimensionException - if the array is not a three dimensional array

getRealArray4D

public double[][][][] getRealArray4D()
Equivalent to getRealArray(DoubleArrayType.DIM_4).

Returns:
Throws:
MatlabNumericArray.ArrayDimensionException - if the array is not a four dimensional array

getImaginaryArray

public <T> T getImaginaryArray(MatlabNumericArray.DoubleArrayType<T> type)
Returns a double array of type T that holds the imaginary values from the MATLAB array.

Type Parameters:
T -
Parameters:
type -
Returns:
Throws:
MatlabNumericArray.ArrayDimensionException - if the array is not of the dimension specified by type
java.lang.IllegalStateException - if the array is real

getImaginaryArray2D

public double[][] getImaginaryArray2D()
Equivalent to getImaginaryArray(DoubleArrayType.DIM_2).

Returns:
Throws:
MatlabNumericArray.ArrayDimensionException - if the array is not a two dimensional array
java.lang.IllegalStateException - if the array is real

getImaginaryArray3D

public double[][][] getImaginaryArray3D()
Equivalent to getImaginaryArray(DoubleArrayType.DIM_3).

Returns:
Throws:
MatlabNumericArray.ArrayDimensionException - if the array is not a three dimensional array
java.lang.IllegalStateException - if the array is real

getImaginaryArray4D

public double[][][][] getImaginaryArray4D()
Equivalent to getImaginaryArray(DoubleArrayType.DIM_4).

Returns:
Throws:
MatlabNumericArray.ArrayDimensionException - if the array is not a four dimensional array
java.lang.IllegalStateException - if the array is real

isReal

public boolean isReal()
Returns true if the array has no imaginary values, false otherwise. Equivalent to the MATLAB isreal function.

Returns:

toString

public java.lang.String toString()
Returns a brief description of this array. The exact details of this representation are unspecified and are subject to change.

Overrides:
toString in class java.lang.Object
Returns: