com.mathworks.toolbox.javabuilder.MWStringArray Class

Namespace: com.mathworks.toolbox.javabuilder

Java class to manage MATLAB string arrays

Description

Declaration

public class MWStringArray extends MWArray

The MWStringArray class manages a native MATLAB^® string array.

Implemented Interfaces: Disposable, java.io.Serializable, java.lang.Cloneable, java.lang.Comparable

Runtime Dependency and Initialization Requirements

MWArray API types represent native MATLAB arrays and are intended for use when MATLAB Runtime is available as part of Java^® Package Integration. To ensure MATLAB Runtime is ready, instantiate the generated class or initialize runtime configuration before invoking packaged code.

Instantiating a class from the Java package generated by MATLAB Compiler SDK™ is the recommended method to ensure the runtime is started. Calling com.mathworks.toolbox.javabuilder.MWApplication.initialize prepares the process environment but does not start MATLAB Runtime. If the runtime is not started by a class instantiation, MWStringArray constructors will fail.

This class is only supported for in-process execution. It cannot be used when working with an out-of-process MATLAB Runtime.

If you cannot instantiate an object from the generated Java package before creating an array, use the MWCharArray class to pass character data. Alternatively, include a method in your MATLAB code that performs no operation and invoke it immediately after instantiating the Java class to trigger the runtime startup.

Creation

MWStringArray()

Creates an empty string array. Requires an active MATLAB Runtime.

MWStringArray(int[] dims)

Creates an n-dimensional string array with all elements set to the default value. Requires an active MATLAB Runtime.

MWStringArray(java.lang.String val)

Creates a one-element string array that represents the Java string argument. Requires an active MATLAB Runtime.

MWStringArray(java.lang.String[] vals)

Creates a string array that represents the Java string array argument. Requires an active MATLAB Runtime.

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. Example: Getting the Class ID of a String Array Create an MWStringArray object and then display the class ID: MWStringArray A = new MWStringArray("Hello"); System.out.println("The class of A is " + A.classID()); When run, the example displays this output: The class of A is string Returns: MWClassID of this array.
`clone`	`public java.lang.Object clone() throws java.lang.CloneNotSupportedException` Creates and returns a deep copy of this array. Changing the data in a deep copy does not change the original array. Example: Cloning a String Array Object Create a clone of MWStringArray object A as follows: MWStringArray A = new MWStringArray("Hello"); MWStringArray C = (MWStringArray)A.clone(); System.out.println("Clone of matrix A is:"); System.out.println(C.get(1)); When run, the example displays this output: Clone of matrix A is: Hello Returns: An MWStringArray 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 interface `java.lang.Comparable` Specified by: `compareTo` in class MWArray 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 Parameters: obj Object Array to compare with this MWArray object
`get`	`public java.lang.Object get(int index)` Returns the string at the specified 1-based offset. Parameters: index The index of the requested element. Valid range: 1 <= index <= N, where N = total number of elements in the array. Returns: Value of the requested element. Null if the element is unset. Throws: java.lang.RuntimeException Used for representing unchecked exceptions, typically indicating programming errors that the programmer should fix rather than catch.
`get`	`public java.lang.Object get(int[] indices)` Returns the string at the specified indices. Parameters: indices The indices of the requested element. Returns: Value of the requested element. Null if the element is unset. Throws: java.lang.RuntimeException Used for representing unchecked exceptions, typically indicating programming errors that the programmer should fix rather than catch. java.lang.NullPointerException Used to signal that an application is attempting to use `null` where an object is required, highlighting unintended null reference errors.
`getData`	`public java.lang.Object getData()` Returns a 1-D string array containing a copy of the data in the underlying MATLAB array. Returns: A 1-D string array of elements stored in column-wise order. The length of the returned array equals `numberOfElements()`.
`getDimensions`	`public int[] getDimensions()` Returns an array containing the size of each dimension of this array. Parameters: index Returns: An Array of dimension sizes. Throws: java.lang.RuntimeException Used for representing unchecked exceptions, typically indicating programming errors that the programmer should fix rather than catch.
`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
`IsMissingElement`	`public boolean IsMissingElement(int index)` Checks if the element at the specified 1-based offset of this array has the value "missing". Parameters: index The offset of the requested element in the array. Returns: A boolean to indicate if the requested element is in missing/unset state. Throws: java.lang.RuntimeException Used for representing unchecked exceptions, typically indicating programming errors that the programmer should fix rather than catch.
`IsMissingElement`	`public boolean IsMissingElement(int[] indices)` Checks if the element at the specified indices of this array has the value "missing". Parameters: indices The indices of the requested element. Returns: A boolean to indicate if the requested element is in missing/unset state. Throws: java.lang.RuntimeException Used for representing unchecked exceptions, typically indicating programming errors that the programmer should fix rather than catch.
`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 an array. If the underlying array is non-sparse, this method returns the same value as `numberOfElements()`. Returns: Currently allocated number of non-zero elements.
`newInstance`	`public static MWStringArray newInstance(int[] dims)` Constructs a string array with the specified dimensions. The elements of the array are all initialized to the default value. Parameters: dims Array of dimension sizes. Each dimension size must be non-negative. Returns: A new MWStringArray with the specified dimensions. Throws: java.lang.RuntimeException Thrown if MATLAB Runtime has not been initialized by an instance of a class from the generated Java package or if the application is running out-of-process.
`numberOfDimensions`	`public int numberOfDimensions()` Returns the number of dimensions of this array. Returns: The number of dimensions. Throws: java.lang.RuntimeException Thrown if MATLAB Runtime has not been initialized by an instance of a class from the generated Java package or if the application is running out-of-process.
`numberOfElements`	`public int numberOfElements()` Returns the number of elements of this array. Returns: The number of elements. Throws: java.lang.RuntimeException Thrown if MATLAB Runtime has not been initialized by an instance of a class from the generated Java package or if the application is running out-of-process.
`numberOfNonZeros`	`public int numberOfNonZeros()` Returns the number of non-zero elements in an array. If the underlying array is non-sparse, this method returns the same value as `numberOfElements()`. Returns: Current number of non-zero elements.
`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 java.io.ObjectStreamException Serves as a base class for exceptions specific to serialization and deserialization processes of objects.
`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 string at the specified 1-based offset in this array with the specified string value. Parameters: index The offset of the element to replace. Valid range: 1 <= index <= N, where N = total number of elements in the array. element New value to replace at index. Pass null to unset the element. Throws: java.lang.RuntimeException Thrown if MATLAB Runtime has not been initialized by an instance of a class from the generated Java package or if the application is running out-of-process.
`set`	`public void set(int[] indices, java.lang.Object element)` Replaces the string at the specified indices in this array with the specified string value. Parameters: indices The indices of the element to replace. element New value to replace at index. Pass null to unset the element. Throws: java.lang.RuntimeException Thrown if MATLAB Runtime has not been initialized by an instance of a class from the generated Java package or if the application is running out-of-process. java.lang.NullPointerException Used to signal that an application is attempting to use `null` where an object is required, highlighting unintended null reference errors.
`setData`	`public void setData(java.lang.Object data)` Sets the elements of this array in column-major order until the input strings are all consumed or all elements of this array are updated, whichever comes first. Parameters: data A String or String[]. Pass null to unset all the elements. Returns: Throws: java.lang.RuntimeException Thrown if MATLAB Runtime has not been initialized by an instance of a class from the generated Java package or if the application is running out-of-process. java.lang.IllegalArgumentException Indicates that a method has been passed an illegal or inappropriate argument.
`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. Example: Making a Shared Copy of a String Array Object Create a shared copy of MWStringArray object A as follows: MWStringArray A = new MWStringArray("Hello"); MWStringArray S = (MWStringArray)A.sharedCopy(); System.out.print("Shared copy of matrix A is \"" + S.get(1) + "\""); When run, the example displays this output: Shared copy of matrix A is "Hello" Returns: An MWStringArray instance representing a shared copy of the underlying MATLAB array.
`toArray`	`public java.lang.Object[] toArray()` Returns a 1-D string array containing a copy of the data in the underlying MATLAB array. Returns: A 1-D string array of elements stored in column-wise order. The length of the returned array equals `numberOfElements()`.
`toString`	`public java.lang.String toString()` Returns a string representation of this array. Returns: null for empty array or string in the form of `[Ljava.lang.String;@443b7951`.
`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

Initialize Runtime for MWStringArray

To use MWStringArray correctly, you must first instantiate the Java class created from your MATLAB code.

// Initialize the application environment
MWApplication.initialize();

// Instantiate the class from the generated Java package to start MATLAB Runtime
// Replace 'MyPackageClass' with the actual class name in your generated package
MyPackageClass component = new MyPackageClass();

// Now MWStringArray can be safely created
MWStringArray A = new MWStringArray("Hello World");
System.out.println(A.toString());

// Dispose of objects
A.dispose();
component.dispose();

Version History

Introduced in R2006a