com.mathworks.toolbox.javabuilder

Class MWStructArray

java.lang.Object

com.mathworks.toolbox.javabuilder.MWArray

com.mathworks.toolbox.javabuilder.MWStructArray

All Implemented Interfaces:

Disposable, java.io.Serializable, java.lang.Cloneable, java.lang.Comparable

public class MWStructArray
extends MWArray

The MWStructArray class manages a native MATLAB struct array.

Since:

1.0

See Also:

Serialized Form

Field Summary

Fields inherited from class com.mathworks.toolbox.javabuilder.MWArray

EMPTY_ARRAY

Constructor Summary

Constructors

Constructor and Description
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.

Method Summary

Modifier and Type	Method and Description
<T> T	applyVisitor(AbstractMWArrayVisitor<T> v)
MWClassID	classID() Returns the MATLAB type of this array.
java.lang.Object	clone() Creates and returns a deep copy of this array.
int[]	columnIndex() Returns an array containing the column index of each element in the underlying MATLAB array.
int	compareTo(java.lang.Object obj) Compares this array with the specified array for order.
static MWArray	deserialize(byte[] data) Create a new MWArray from serialized data.
void	dispose() Frees the native MATLAB array contained by this array.
boolean	equals(java.lang.Object obj) Indicates whether some other array is equal to this one.
int	fieldIndex(java.lang.String fieldname)
java.lang.String[]	fieldNames() Returns the field names in this array.
static MWStructArray	fromBean(java.lang.Object bean)
static MWStructArray	fromMap(java.util.Map<java.lang.String,java.lang.Object> map)
static MWStructArray	fromProperties(java.util.Properties props)
java.lang.Object	get(int index) Returns the element at the specified 1-based offset in this array.
java.lang.Object	get(int[] index) Returns the element at the specified 1-based index-array in this array.
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.
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.
java.lang.Object	getData() Returns a 1-D array containing a copy of the data in the underlying MATLAB array.
int[]	getDimensions() Returns an array containing the size of each dimension of this array.
MWArray	getField(int index) Returns the element at the specified 1-based offset in this array as an MWArray instance.
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.
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.
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.
int	hashCode() Returns a hash code value for this array.
boolean	isEmpty() Tests if this array has no elements.
boolean	isSparse() Tests if this array is sparse.
int	maximumNonZeros() Returns the allocated capacity of a sparse array.
int	numberOfDimensions() Returns the number of dimensions of this array.
int	numberOfElements() Returns the total number of elements in this array.
int	numberOfFields()
int	numberOfNonZeros() Returns the number of non-zero elements in a sparse array.
protected java.lang.Object	readResolve() Called by serialization mechanism when loading a new array from a byte stream.
int[]	rowIndex() Returns an array containing the row index of each element in the underlying MATLAB array.
byte[]	serialize() Serialize the MATLAB array to a byte array.
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.
void	set(int index, java.lang.Object element) Replaces the element at the specified 1-based offset in this array with the specified element.
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.
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.
void	setData(java.lang.Object data)
java.lang.Object	sharedCopy() Creates and returns a shared copy of this array.
java.lang.Object[]	toArray() Returns an array containing a copy of the data in the underlying MATLAB array.
java.lang.String	toString() Returns a string representation of this array.
protected void	validate() Validates the internal array handle.

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

disposeArray

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

MWStructArray

public MWStructArray()

Creates an empty struct array.

Example: Constructing a Structure Array Object

This example creates a 0-by-0 MWStructArray object:

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

When run, the example displays this output:

      Structure array S: []
 

MWStructArray

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

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

Parameters:

dims - Array of dimension sizes. Each dimension size must be non-negative.

fieldnames - Array of field names.

Throws:

java.lang.NegativeArraySizeException - A negative dimension size is supplied.

Example: Constructing a Structure Array Object

This example creates a 1-by-2 MWStructArray object with fields f1, f2, and f3:

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

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

When run, the example displays this output:

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

MWStructArray

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

Parameters:

rows - Number of rows. Number of rows must be non-negative.

cols - Number of columns. Number of columns must be non-negative.

fieldnames - Array of field names.

Throws:

java.lang.NegativeArraySizeException - A negative row or column size is supplied.

Example: Constructing a Structure Array Object

This example creates a 1-by-2 MWStructArray object with fields f1, f2, and f3:

     int rows = 1, cols = 2;

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

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

When run, the example displays this output:

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

Method Detail

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Creates and returns a deep copy of this array.

Returns:

An MWStructArray instance representing a deep copy of the underlying MATLAB 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
 

Throws:

java.lang.CloneNotSupportedException - - The object's class does not implement the Cloneable interface.

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"};
      MWStructArray S = new MWStructArray(sdims, sfields);

      Object C = S.sharedCopy();

      System.out.println("Shared copy of structure S is:");
      System.out.println(C.toString());
 

When run, the example displays this output:

      Shared copy of structure S is:
      1x2 struct array with fields:
          f1
          f2
          f3
 

classID

public MWClassID classID()

Returns the MATLAB type of this array.

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());
 

When run, the example displays this output:

     The class of S is struct
 

numberOfFields

public int numberOfFields()

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.");
 

When run, the example displays this output:

     There are 3 fields in this structure.
 

fieldNames

public java.lang.String[] fieldNames()

Returns the field names in this array.

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
 

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

set

public void set(int index,
                java.lang.Object element)

Replaces the element at the specified 1-based offset in this array with the specified element.

Parameters:

index - The index of the element to replace. 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().

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.

Example: Setting Values in a Structure Array

       int[] sdims = {1, 2};
       String[] sfields = {"f1", "f2", "f3"};

       MWStructArray S = new MWStructArray(sdims, sfields);
       int totNumElem = S.numberOfElements() * S.numberOfFields();

       for (int i = 1; i <= totNumElem; i++)
       {
           S.set(i,i*15);
       }

       int elemCnt = 1;

       for(int r=1; r <= sdims[0]; r++)
       {
           for(int c=1; c <= sdims[1]; c++)
           {
               System.out.println("Element : " + elemCnt++);

               for(int f=0; f < sfields.length; f++)
               {
                   System.out.print("\t" + sfields[f] + " : ");
                   System.out.println(S.getField(sfields[f], new int[]{r,c}));
               }
           }
       }
 

When run, the example displays this output:

      Element : 1
              f1 : 15
              f2 : 30
              f3 : 45
      Element : 2
              f1 : 60
              f2 : 75
              f3 : 90
 

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 offset and field name in this array with the specified element.

Parameters:

fieldname - The field name of the element to replace.

index - The index of the element to replace. Valid range: 1 <= index <= N, where N = numberOfElements()

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.

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 equivelent to calling getField(index).toArray().

Parameters:

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]);
               }
 

When run, the example displays this output:

       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 equivelent 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 equivelent 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 equivelent to calling getField(fieldname, index).toArray().

Parameters:

fieldname - The field name of the requested element.

index - of the requested element.

Returns:

Object containing the requested element.

Throws:

java.lang.IndexOutOfBoundsException - An invalid index has been supplied.

getField

public MWArray getField(int index)

Returns the element at the specified 1-based offset in this array as an MWArray instance.

Parameters:

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

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]);
 

When run, the example displays this output:

     Data read from structure array S:

           15
           30
           45
           60
           75
           90
 

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]);
 

When run, the example displays this output:

      Data read from structure array S

       0 15 30 45 60 75
 

applyVisitor

public <T> T applyVisitor(AbstractMWArrayVisitor<T> v)

validate

protected void validate()

Validates the internal array handle. Called by constructors and deserialization code.

fromMap

public static MWStructArray fromMap(java.util.Map<java.lang.String,java.lang.Object> map)
                             throws MWException

Throws:

MWException

fromBean

public static MWStructArray fromBean(java.lang.Object bean)
                              throws java.beans.IntrospectionException,
                                     MWException

Throws:

java.beans.IntrospectionException

MWException

fromProperties

public static MWStructArray fromProperties(java.util.Properties props)

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.

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

numberOfDimensions

public int numberOfDimensions()

Returns the number of dimensions of this array.

Specified by:

numberOfDimensions in class MWArray

Returns:

number of dimensions

getDimensions

public int[] getDimensions()

Returns an array containing the size of each dimension of this array.

Specified by:

getDimensions in class MWArray

Returns:

array containing size of each dimension

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 sparse, false otherwise

equals

public boolean equals(java.lang.Object obj)

Indicates whether some other array is equal to this one.

Specified by:

equals in class MWArray

Parameters:

obj - Object Array to compare with this MWArray object

compareTo

public int compareTo(java.lang.Object obj)

Compares this array with the specified array for order.

Specified by:

compareTo in interface java.lang.Comparable

Specified by:

compareTo in class MWArray

Parameters:

obj - Object Array to compare with this MWArray object

hashCode

public int hashCode()

Returns a hash code value for this array.

Specified by:

hashCode in class MWArray

toString

public java.lang.String toString()

Returns a string representation of this array.

Specified by:

toString in class MWArray

numberOfElements

public int numberOfElements()

Returns the total number of elements in this array.

Specified by:

numberOfElements in class MWArray

Returns:

number of elements

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.

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.

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

setData

public void setData(java.lang.Object data)

Specified by:

setData in class MWArray

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.

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.

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