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

Author:	Joshua Kaplan

See also: TypeConverter.setNumericArray(java.lang.String,matlabcontrol.extensions.MatlabNumericArray), TypeConverter.getNumericArray(java.lang.String)