com.mathworks.toolbox.javabuilder.MWStructArray Class

Namespace: com.mathworks.toolbox.javabuilder

Java class to manage MATLAB struct arrays

Description

Declaration

public class MWStructArray extends MWArray

The MWStructArray class manages a native MATLAB^® struct array.

Creation

MWStructArray()

Creates an empty struct array.

MWStructArray(int[] dims, java.lang.String[] fieldnames)

Constructs a new struct array with the specified dimensions and field names.

MWStructArray(int rows, int cols, java.lang.String[] fieldnames)

Constructs a new struct matrix with the specified number of rows and columns and field names.

Properties

expand all

Public Properties

`EMPTY_ARRAY` — Represent an empty array
`public static final MWArray`

A convenient, efficient, and consistent way to represent an empty array as follows:

public static final MWArray EMPTY_ARRAY

Methods

expand all

Public Methods

`applyVisitor`	`public abstract <T> T applyVisitor(AbstractMWArrayVisitor<T> v)` This method is abstract and returns a type specified by the type parameter <T>. It takes an instance of `AbstractMWArrayVisitor<T>` as an argument. The purpose of this method is to apply the visitor pattern to an MWArray object. By calling this method with an appropriate visitor, you can traverse and perform operations on elements of the MWArray in a type-safe manner. Parameters: v An instance of `AbstractMWArrayVisitor<T>` representing the visitor to be applied to the MWArray object. Returns: T The result of applying the visitor to the MWArray object, with the specific type specified by <T>.
`classID`	`public MWClassID classID()` Returns the MATLAB type of this array. Parameters: index Returns: Returns `MWClassID.STRUCT` for MWStructArray. Example: Getting the Class ID of a Structure Array Create an MWStructArray object and display the class ID: int[] sdims = {1, 2}; String[] sfields = {"f1", "f2", "f3"}; MWStructArray S = new MWStructArray(sdims, sfields); System.out.println("The class of S is " + S.classID()); The class of S is struct
`clone`	`public java.lang.Object clone() throws java.lang.CloneNotSupportedException` Creates and returns a deep copy of this array. Example: Cloning a Structure Array Object Create an `MWStructArray` object and then a clone of that object: int[] sdims = {1, 2}; String[] sfields = {"f1", "f2", "f3"}; MWStructArray S = new MWStructArray(sdims, sfields); Object C = S.clone(); System.out.println("Clone of structure S is:"); System.out.println(C.toString()); When run, the example displays this output: Clone of structure S is: 1x2 struct array with fields: f1 f2 f3 Returns: An `MWStructArray` instance representing a deep copy of the underlying MATLAB array. Throws: java.lang.CloneNotSupportedException The object's class does not implement the Cloneable interface.
`columnIndex`	`public int[] columnIndex()` Returns an array containing the column index of each element in the underlying MATLAB array. Specified by: `columnIndex` in class MWArray Returns: Array of indices.
`compareTo`	`public int compareTo(java.lang.Object obj)` Compares this array with the specified array for order. Specified by: `compareTo` in class MWArray Specified by: `compareTo` in class `java.lang.Comparable` Parameters: obj Object Array to compare with this MWArray object.
`deserialize`	`public static MWArray deserialize(byte[] data)` Create a new MWArray from serialized data. Parameters: data serialized array returned from `MWArray.serialize`. Returns: The deserialized MWArray.
`dispose`	`public void dispose()` Frees the native MATLAB array contained by this array. Specified by: `dispose` in interface Disposable Specified by: `dispose` in class MWArray
`equals`	`public boolean equals(java.lang.Object obj)` Indicates whether some other array is equal to this one. Specified by: `equals` in class MWArray Throws: obj Object Array to compare with this MWArray object.
`fieldIndex`	`public int fieldIndex(java.lang.String fieldname)` Parameters: fieldname The name of the field to look up. Returns: The index of the given field name.
`fieldNames`	`public java.lang.String[] fieldNames()` Returns the field names in this array. Parameters: index Returns: An array of Strings representing the field names. Example: Getting the Field Names of a Structure Array Create an MWStructArray object with three fields and display the field names: int[] sdims = {1, 2}; String[] sfields = {"f1", "f2", "f3"}; MWStructArray S = new MWStructArray(sdims, sfields); String[] str = S.fieldNames(); System.out.print("The structure has the fields: "); for (int i=0; i < S.numberOfFields(); i++) System.out.print(" " + str[i]); When run, the example displays this output: The structure has the fields: f1 f2 f3
`fromBean`	`public static MWStructArray fromBean(java.lang.Object bean) throws java.beans.IntrospectionException, MWException` Throws: java.beans.IntrospectionException An invalid index has been supplied. MWException Exception.
`fromMap`	`public static MWStructArray fromMap(java.util.Map<java.lang.String,java.lang.Object> map) throws MWException` Throws: MWException Exception.
`fromProperties`	`public static MWStructArray fromProperties(java.util.Properties props)`
`get`	`public java.lang.Object get(int index)` Returns the element at the specified 1-based offset in this array. The returned element is converted to a Java^® array using default conversion rules. Calling this method is equivalent to calling `getField(index).toArray()`. Parameters: index Index of requested element. Valid range: 1 <= index <= N, where N = total number of elements in the array. The total number of elements for a struct array = `numberOfElements()``numberOfFields()`. Returns:* Object containing the requested element. Throws: java.lang.IndexOutOfBoundsException An invalid index has been supplied. Example: Getting Structure Array Data with get int[] cdims = {1, 3}; MWStructArray C = new MWStructArray(cdims); Integer val = new Integer(15); int[] index2 = {1, 3}; C.set(index2, val); Object x = C.get(index2); if (x instanceof int[][]) { int[][] y = (int[][])x; System.out.println("B: Cell data C(1,3) is " + y[0][0]); } B: Cell data C(1,3) is 15
`get`	`public java.lang.Object get(int[] index)` Returns the element at the specified 1-based index-array in this array. The returned element is converted to a Java array using default conversion rules. Calling this method is equivalent to calling `getField(index).toArray()`. Parameters: index Array of indices specifying the location of requested element. The length of the index array must be exactly numberOfDimensions() + 1. The first element of the index array is the 1-based field number with valid range 1 <= index[0] <= numberOfFields(). The remaining entries have valid ranges: 1 <= index[i] <= N[i], where N[i] = the size of the ith dimension. Returns: Object containing the requested element. Throws: java.lang.IndexOutOfBoundsException An invalid index has been supplied.
`get`	`public java.lang.Object get(java.lang.String fieldname, int[] index)` Returns the element at the specified 1-based index-array and field name in this array. The returned element is converted to a Java array using default conversion rules. Calling this method is equivalent to calling `getField(fieldname, index).toArray()`. Parameters: fieldname The field name of the requested element. index Array of indices specifying the location of the requested element. The length of the index array must be exactly numberOfDimensions(). The entries of the index array have valid ranges: 1 <= index[i] <= N[i], where N[i] = the size of the ith dimension. Returns: Object containing the requested element. Throws: java.lang.IndexOutOfBoundsException An invalid index has been supplied.
`get`	`public java.lang.Object get(java.lang.String fieldname, int index)` Returns the element at the specified 1-based offset and field name in this array. The returned element is converted to a Java array using default conversion rules. Calling this method is equivalent to calling `getField(fieldname, index).toArray()`. Parameters: fieldname The field name of the requested element. index Index of the requested element. Returns: Object containing the requested element. Throws: java.lang.IndexOutOfBoundsException An invalid index has been supplied.
`getData`	`public java.lang.Object getData()` Returns a 1-D array containing a copy of the data in the underlying MATLAB array. Returns: A 1-D array of elements stored in column-wise order. Before converting, a new array is derived by transforming the struct array into a cell array such that a n by m by ... struct array with p fields is transformed into a p by n by m by ... cell array. Each element in the returned array is converted to a Java array by calling `MWArray.toArray()` on the corresponding cell. Example: Getting Structure Array Data with getData Get the data stored in all fields and indices of MWStructArray object S: int[] sdims = {1, 2}; String[] sfields = {"f1", "f2", "f3"}; MWStructArray S = new MWStructArray(sdims, sfields); int count = S.numberOfElements() * S.numberOfFields(); // Initialize the structure. Integer[] val = new Integer[6]; for (int i = 0; i < count; i++) val[i] = new Integer((i+1) * 15); // Use getData to get data from the structure. System.out.println("Data read from structure array S: \n"); MWArray[] x = (MWArray[]) S.getData(); for (int i = 0; i < x.length; i++) System.out.print(" " + x[i]); Data read from structure array S: 15 30 45 60 75 90
`getDimensions`	`public int[] getDimensions()` Returns the number of dimensions of this array. Returns: Number of dimensions.
`getField`	`public MWArray getField(int index)` Returns the element at the specified 1-based offset in this array as an MWArray instance. Parameters: index Index of requested element. Valid range: 1 <= index <= N, where N = total number of elements in the array. The total number of elements for a struct `array = numberOfElements()numberOfFields`. Returns:* An MWArray instance representing the requested field. This MWArray reference should be disposed by calling `MWArray.dispose()`. Throws: java.lang.IndexOutOfBoundsException An invalid index has been supplied.
`getField`	`public MWArray getField(int[] index)` Returns a shared copy of the element at the specified 1-based index-array in this array as an MWArray instance. Parameters: index Array of indices specifying the location of requested element. The length of the index array must be exactly numberOfDimensions() + 1. The first element of the index array is the 1-based field number with valid range 1 <= index[0] <= numberOfFields(). The remaining entries have valid ranges: 1 <= index[i] <= N[i], where N[i] = the size of the ith dimension. Returns: An MWArray instance representing the requested field. This MWArray reference should be disposed by calling `MWArray.dispose()`. Throws: java.lang.IndexOutOfBoundsException An invalid index has been supplied.
`getField`	`public MWArray getField(java.lang.String fieldname, int[] index)` Returns a shared copy of the element at the specified 1-based index-array and field name in this array as an MWArray instance. Parameters: fieldname The field name of the requested element. index Array of indices specifying the location of the requested element. The length of the index array must be exactly numberOfDimensions(). The entries of the index array have valid ranges: 1 <= index[i] <= N[i], where N[i] = the size of the ith dimension. Returns: An MWArray instance representing the requested field. This MWArray reference should be disposed by calling `MWArray.dispose()`. Throws: java.lang.IndexOutOfBoundsException An invalid index has been supplied.
`getField`	`public MWArray getField(java.lang.String fieldname, int index)` Returns a shared copy of the element at the specified 1-based offset and field name in this array as an MWArray instance. Parameters: fieldname The field name of the requested element. index Index of the requested element. Valid range: 1 <= index <= numberOfElements. Returns: An MWArray instance representing the requested field. This MWArray reference should be disposed by calling `MWArray.dispose()`. Throws: java.lang.IndexOutOfBoundsException An invalid index has been supplied.
`hashCode`	`public int hashCode()` Returns a hash code value for this array. Specified by: `hashCode` in class `MWArray`.
`isEmpty`	`public boolean isEmpty()` Tests if this array has no elements. Specified by: `isEmpty` in class `MWArray`. Returns: `true` if empty, `false` otherwise
`isSparse`	`public boolean isSparse()` Tests if this array is sparse. Specified by: `isSparse` in class `MWArray`. Returns: `true` if empty, `false` otherwise
`maximumNonZeros`	`public int maximumNonZeros()` Returns the allocated capacity of a sparse array. If the underlying array is non-sparse, this method returns the same value as `numberOfElements()`. Specified by: `maximumNonZeros` in class `MWArray`. Returns: Currently allocated number of non-zero elements in a sparse array.
`numberOfDimensions`	`public int numberOfDimensions()` Returns the number of dimensions of this array. Specified by: `numberOfDimensions` in class `MWArray`. Returns: number of dimensions
`numberOfElements`	`public int numberOfElements()` Returns the total number of elements in this array. Specified by: `numberOfElements` in class `MWArray`. Returns: number of elements
`numberOfFields`	`public int numberOfFields()` Returns the number of fields in this array. Returns: The number of fields in this array. Example: Getting the Number of Fields in a Structure Array Create an MWStructArray object with three fields and display the number of fields: int[] sdims = {1, 2}; String[] sfields = {"f1", "f2", "f3"}; MWStructArray S = new MWStructArray(sdims, sfields); String[] str = S.fieldNames(); System.out.println("There are " + S.numberOfFields() + " fields in this structure."); Output: There are 3 fields in this structure.
`numberOfNonZeros`	`public int numberOfNonZeros()` Returns the number of non-zero elements in a sparse array. If the underlying array is non-sparse, this method returns the same value as `numberOfElements()`. Specified by: `numberOfNonZeros` in class `MWArray`. Returns: Current number of non-zero elements in a sparse array.
`readResolve`	`protected java.lang.Object readResolve() throws java.io.ObjectStreamException` Called by serialization mechanism when loading a new array from a byte stream. This method validates the correct array type. Returns: Returns this Object indicating validated array type. Throws: java.io.InvalidObjectException Attempt to load an invalid array handle. java.io.ObjectStreamException Object stream exception.
`rowIndex`	`public int[] rowIndex()` Returns an array containing the row index of each element in the underlying MATLAB array. Specified by: `rowIndex` in class `MWArray`. Returns: Array of indices.
`serialize`	`public byte[] serialize() throws java.io.IOException` Serialize the MATLAB array to a byte array. Returns: The serialized MATLAB array data. Throws: java.io.IOException If the array cannot be serialized. For example, executable content (function handles, class instances) cannot be serialized.
`set`	`public void set(int[] index, java.lang.Object element)` Replaces the element at the specified 1-based index-array in this array with the specified element. Parameters: index Array of indices specifying the location of the element to replace. The length of the index array must be exactly numberOfDimensions() + 1. The first element of the index array is the 1-based field number with valid range 1 <= index[0] <= numberOfFields(). The remaining entries have valid ranges: 1 <= index[i] <= N[i], where N[i] = the size of the ith dimension. element New element to replace at index. If element is of type MWArray, the cell at index set to a shared copy of the underlying MATLAB array. Otherwise, a new MATLAB array is created from element using default conversion rules and assigned to the cell at index. Throws: java.lang.IndexOutOfBoundsException An invalid index has been supplied.
`set`	`public void set(java.lang.String fieldname, int[] index, java.lang.Object element)` Replaces the element at the specified 1-based index-array and field name in this array with the specified element. Parameters: fieldname The field name of the element to replace. index Array of indices specifying the location of the element to replace. The length of the index array must be exactly numberOfDimensions(). The entries of the index array have valid ranges: 1 <= index[i] <= N[i], where N[i] = the size of the ith dimension. element New element to replace at index. If element is of type MWArray, the cell at index set to a shared copy of the underlying MATLAB array. Otherwise, a new MATLAB array is created from element using default conversion rules and assigned to the cell at index. Throws: java.lang.IndexOutOfBoundsException An invalid index has been supplied.
`set`	`public void set(java.lang.String fieldname, int[] index, java.lang.Object element)` Replaces the element at the specified 1-based index-array and field name in this array with the specified element. Parameters: fieldname The field name of the element to replace. index Array of indices specifying the location of the element to replace. The length of the index array must be exactly numberOfDimensions(). The entries of the index array have valid ranges: 1 <= index[i] <= N[i], where N[i] = the size of the ith dimension. element New element to replace at index. If element is of type MWArray, the cell at index set to a shared copy of the underlying MATLAB array. Otherwise, a new MATLAB array is created from element using default conversion rules and assigned to the cell at index. Throws: java.lang.IndexOutOfBoundsException An invalid index has been supplied.
`set`	`public void set(java.lang.String fieldname, int index, java.lang.Object element)` Replaces the element at the specified 1-based offset and field name in this array with the specified element. Parameters: fieldname The field name of the element to replace. index Array of indices specifying the location of the element to replace. The length of the index array must be exactly numberOfDimensions(). The entries of the index array have valid ranges: 1 <= index[i] <= N[i], where N[i] = the size of the ith dimension. element New element to replace at index. If element is of type MWArray, the cell at index set to a shared copy of the underlying MATLAB array. Otherwise, a new MATLAB array is created from element using default conversion rules and assigned to the cell at index. Throws: java.lang.IndexOutOfBoundsException An invalid index has been supplied.
`setData`	`public void setData(java.lang.Object data)` Specified by: `setData` in class `MWArray`.
`sharedCopy`	`public java.lang.Object sharedCopy()` Creates and returns a shared copy of this array. A shared copy points to the same underlying MATLAB array as the original. Changing the data in a shared copy also changes the original array. Returns: An MWStructArray instance representing a shared copy of the underlying MATLAB array. Example: Making a Shared Copy of a Structure Array Object Create an MWStructArray object and then a shared copy of that object: int[]sdims={1,2}; String[]sfields={"f1","f2","f3"}; MWStructArrayS=newMWStructArray(sdims,sfields); ObjectC=S.sharedCopy(); System.out.println("SharedcopyofstructureSis:"); System.out.println(C.toString()); Output: Shared copy of structure S is: 1x2 struct array with fields: f1 f2 f3
`toArray`	`public java.lang.Object[] toArray()` Returns an array containing a copy of the data in the underlying MATLAB array. Returns: An array with the same dimensionality of the MATLAB array. Before converting, a new array is derived by transforming the struct array into a cell array such that a n by m by ... struct array with p fields is transformed into a p by n by m by ... cell array. Each element in the returned array is converted to a Java array by calling MWArray.toArray() on the corresponding cell. Example: Getting Structure Array Data with toArray int[] sdims = {1, 2}; String[] sfields = {"f1", "f2", "f3"}; MWStructArray S = new MWStructArray(sdims, sfields); Integer[] val = new Integer[25]; for (int i = 0; i < 6; i++) val[i] = new Integer(i * 15); for (int i = 0; i < 2; i++) for (int j = 0; j < sfields.length; j++) S.set(sfields[j], i+1, val[j + (i * 3)]); Object[][][] x = (Object[][][]) S.toArray(); System.out.println(); System.out.println("Data read from structure array S \n"); for (int j = 0; j < 2; j++) for (int i = 0; i < x.length; i++) System.out.print(" " + ((int[][]) x[i][0][j])[0][0]); Output: Data read from structure array S 0 15 30 45 60 75
`toString`	`public java.lang.String toString()` Returns a string representation of this array. Specified by: `toString` in class `MWArray`.
`validate`	`protected void validate()` Validates the internal array handle. Called by constructors and deserialization code.

Inherited Methods

Methods inherited from class com.mathworks.toolbox.javabuilder.MWArray:

disposeArray

public static void disposeArray(java.lang.Object obj)

This method destroys any native MATLAB arrays contained in the input object and frees the memory occupied by them. This is a static method of the class and thus does not need to be invoked in reference to an instance of the class. If the input object implements the Disposable interface, the object is freed by calling its Disposable.dispose() method. If the input object represents an array of Disposable instances, each object in the array is disposed. If the input object represents an array of java.lang.Object, or a multi-dimensional array, the array is recursively processed to free each Disposable instance contained in the array.

Example: Constructing an MWNumericArray Object

MWArray[] MArr = new MWArray[10];
for (int i = 0; i < 10; i++)
    MArr[i] = new MWNumericArray();
MWArray.disposeArray(MArr);

Parameters:

obj: Object to process.

Methods inherited from class java.lang.Object.

`finalize`	`finalize()` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
`getClass`	`public final Class<?> getClass()` Returns the runtime class of this Object.
`notify`	`public final void notify()`
`notifyAll`	`public final void notifyAll()` Wakes up all threads that are waiting on this object's monitor.
`wait`	`public final void wait(long timeout, int nanos) throws InterruptedException` Causes the current thread to wait until another thread invokes the `notify()` method or the `notifyAll()` method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed.

Examples

collapse all

Create an Empty Struct Array

MWStructArray S = new MWStructArray();
System.out.println("Structure array S: " + S);

Structure array S: []

Constructs Struct Array with Specified Dimensions and Field Names

String[] sfields = {"f1", "f2", "f3"};
int[] dims       = new int[]{1,2};
MWStructArray S = new MWStructArray(dims, sfields);

Structure array S: 1x2 struct array with fields:
         f1
         f2
         f3

Construct New Struct Matrix with Specified Number of Rows, Columns, and Field Names

int rows = 1, cols = 2;

String[] sfields = {"f1", "f2", "f3"};
MWStructArray S = new MWStructArray(rows, cols, sfields);

System.out.println("Structure array S: " + S);

Version History

Introduced in R2006a