com.mathworks.toolbox.javabuilder

Class MWStringArray

java.lang.Object

com.mathworks.toolbox.javabuilder.MWArray

com.mathworks.toolbox.javabuilder.MWStringArray

All Implemented Interfaces:

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

public class MWStringArray
extends MWArray

The MWStringArray class manages a native MATLAB string array.

See Also:

Serialized Form

Field Summary

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

EMPTY_ARRAY

Constructor Summary

Constructors

Constructor and Description
MWStringArray() Creates an empty string array.
MWStringArray(int[] dims) Creates an n-dimentional string array with all elements in default value.
MWStringArray(java.lang.String val) Creates a one-element string array that represents the java string argument.
MWStringArray(java.lang.String[] vals) Creates a string array that represents the java String[] argument.

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.
java.lang.Object	get(int index) Returns the string at the specified 1-based offset.
java.lang.Object	get(int[] indices) Returns the string at the specified indices .
java.lang.Object	getData() Returns a 1-D string 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.
int	hashCode() Returns a hash code value for this array.
boolean	isEmpty() Tests if this array has no elements.
boolean	IsMissingElement(int index) Checks if the element at the specified 1-based offset of this array has the value "missing".
boolean	IsMissingElement(int[] indices) Checks if the element at the specified indices of this array has the value "missing".
boolean	isSparse() Tests if this array is sparse.
int	maximumNonZeros() Returns the allocated capacity of a array.
static MWStringArray	newInstance(int[] dims) Constructs a string array with the specified dimensions.
int	numberOfDimensions() Returns the number of dimensions of this array.
int	numberOfElements() Returns the number of elements of this array.
int	numberOfNonZeros() Returns the number of non-zero elements in a 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[] indices, java.lang.Object element) Replaces the string at the specified indices in this array with the specified string value.
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.
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.
java.lang.Object	sharedCopy() Creates and returns a shared copy of this array.
java.lang.Object[]	toArray() Returns a 1-D string 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

MWStringArray

public MWStringArray()

Creates an empty string array.

Throws:

java.lang.RuntimeException

MWStringArray

public MWStringArray(int[] dims)

Creates an n-dimentional string array with all elements in default value.

Parameters:

dims - Array of dimension sizes. Each dimension size must be greater than zero.

Throws:

java.lang.RuntimeException

MWStringArray

public MWStringArray(java.lang.String val)

Creates a one-element string array that represents the java string argument.

Parameters:

val - The value to initialize the array element.

Throws:

java.lang.RuntimeException

MWStringArray

public MWStringArray(java.lang.String[] vals)

Creates a string array that represents the java String[] argument.

Parameters:

vals - The values to initialize the array elements.

Throws:

java.lang.RuntimeException

Method Detail

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.

Returns:

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

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 MWStringArray instance representing a shared copy of the underlying MATLAB 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"
 

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

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

java.lang.RuntimeException

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

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

java.lang.RuntimeException

classID

public MWClassID classID()

Returns the MATLAB type of this array.

Returns:

returns MWClassID.CHAR for MWStringArray.

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
 

applyVisitor

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

validate

protected void validate()

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

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.

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

numberOfElements

public int numberOfElements()

Returns the number of elements of this array.

Returns:

The number of elements.

Throws:

java.lang.RuntimeException

numberOfDimensions

public int numberOfDimensions()

Returns the number of dimensions of this array.

Returns:

The number of dimensions.

Throws:

java.lang.RuntimeException

getDimensions

public int[] getDimensions()

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

Returns:

An Array of dimension sizes.

Throws:

java.lang.RuntimeException

numberOfNonZeros

public int numberOfNonZeros()

Returns the number of non-zero elements in a array. If the underlying array is non-sparse, this method returns the same value as numberOfElements().

Returns:

Current number of non-zero elements.

maximumNonZeros

public int maximumNonZeros()

Returns the allocated capacity of a array. If the underlying array is non-sparse, this method returns the same value as numberOfElements().

Returns:

Currently allocated number of non-zero elements.

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

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

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.

Throws:

java.lang.IllegalArgumentException

java.lang.RuntimeException

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

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.

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

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

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

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

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