java.lang.Object
- 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

Nested Classes
Modifier and Type	Class	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 Summary

Constructors
Constructor	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.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method	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 linearIndex)`	Gets the imaginary value at `linearIndex` treating this array as the underlying one dimensional array.
`double`	`getImaginaryValue(int... indices)`	Gets the imaginary value at the specified `indices`.
`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 linearIndex)`	Gets the real value at `linearIndex` treating this array as the underlying one dimensional array.
`double`	`getRealValue(int... indices)`	Gets the real value at the specified `indices`.
`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:

Class MatlabNumericArray

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

MatlabNumericArray

MatlabNumericArray

MatlabNumericArray

MatlabNumericArray

Method Detail

getRealValue

getImaginaryValue

getRealValue

getImaginaryValue

getDimensions

getLengths

getLength

getRealArray

getRealArray2D

getRealArray3D

getRealArray4D

getImaginaryArray

getImaginaryArray2D

getImaginaryArray3D

getImaginaryArray4D

isReal

toString