com.mathworks.toolbox.javabuilder

Class MWLogicalArray

java.lang.Object

com.mathworks.toolbox.javabuilder.MWArray

com.mathworks.toolbox.javabuilder.MWLogicalArray

All Implemented Interfaces:

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

public class MWLogicalArray
extends MWArray

The MWLogicalArray class manages a native MATLAB logical 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
MWLogicalArray() Creates an Empty logical array.
MWLogicalArray(boolean val) Constructs a new scalar logical array that represents the primitive boolean argument.
MWLogicalArray(byte val) Constructs a new scalar logical array that represents the primitive byte argument.
MWLogicalArray(double val) Constructs a new scalar logical array that represents the primitive double argument.
MWLogicalArray(float val) Constructs a new scalar logical array that represents the primitive float argument.
MWLogicalArray(int val) Constructs a new scalar logical array that represents the primitive int argument.
MWLogicalArray(long val) Constructs a new scalar logical array that represents the primitive long argument.
MWLogicalArray(java.lang.Object val) Constructs a logical array that represents the Object argument.
MWLogicalArray(short val) Constructs a new scalar logical array that represents the primitive short argument.

Method Summary

Methods

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 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.
boolean	getBoolean(int index) Returns the boolean at the specified 1-based offset.
boolean	getBoolean(int[] index) Returns the boolean at the specified 1-based index-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.
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.
static MWLogicalArray	newInstance(int[] dims) Constructs a logical array with the specified dimensions.
static MWLogicalArray	newInstance(int[] dims, java.lang.Object data) Constructs a logical array with the specified dimensions and initializes the array with the supplied data.
static MWLogicalArray	newSparse(int[] rowindex, int[] colindex, java.lang.Object data) Constructs a sparse logical matrix with the number of rows = max{rowindex(k)} and the number of columns = max{colindex(k)}, and initializes the array with the supplied data.
static MWLogicalArray	newSparse(int[] rowindex, int[] colindex, java.lang.Object data, int rows, int cols) Constructs a sparse logical matrix with the specified number of rows and columns, and initializes the array with the supplied data.
static MWLogicalArray	newSparse(int[] rowindex, int[] colindex, java.lang.Object data, int rows, int cols, int nzmax) Constructs a sparse logical matrix with the specified number of rows and columns, maximum nonzero elements, and initializes the array with the supplied data.
static MWLogicalArray	newSparse(int rows, int cols, int nzmax) Constructs a sparse logical matrix with no nonzero elements.
static MWLogicalArray	newSparse(java.lang.Object arr) Constructs a sparse logical matrix from the supplied full matrix.
int	numberOfDimensions() Returns the number of dimensions of this array.
int	numberOfElements() Returns the total number of elements in this array.
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, boolean element) Replaces the element at the specified 1-based index-array in this array with the specified boolean value.
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, boolean element) Replaces the element at the specified 1-based offset in this array with the specified boolean value.
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	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

MWLogicalArray

public MWLogicalArray()

Creates an Empty logical array.

MWLogicalArray

public MWLogicalArray(boolean val)

Constructs a new scalar logical array that represents the primitive boolean argument.

Parameters:

val - The value to initialize the array with.

Example: Constructing an Initialized Logical Array Object

     boolean[][] Adata = {{true, false, false},
                          {false, true, false}};
 
     MWLogicalArray A = new MWLogicalArray(Adata);
 

MWLogicalArray

public MWLogicalArray(double val)

Constructs a new scalar logical array that represents the primitive double argument. The value of the array is set to true if the argument is non-zero, and false otherwise.

Parameters:

val - The value to initialize the array with.

MWLogicalArray

public MWLogicalArray(float val)

Constructs a new scalar logical array that represents the primitive float argument. The value of the array is set to true if the argument is non-zero, and false otherwise.

Parameters:

val - The value to initialize the array with.

MWLogicalArray

public MWLogicalArray(byte val)

Constructs a new scalar logical array that represents the primitive byte argument. The value of the array is set to true if the argument is non-zero, and false otherwise.

Parameters:

val - The value to initialize the array with.

MWLogicalArray

public MWLogicalArray(short val)

Constructs a new scalar logical array that represents the primitive short argument. The value of the array is set to true if the argument is non-zero, and false otherwise.

Parameters:

val - The value to initialize the array with.

MWLogicalArray

public MWLogicalArray(int val)

Constructs a new scalar logical array that represents the primitive int argument. The value of the array is set to true if the argument is non-zero, and false otherwise.

Parameters:

val - The value to initialize the array with.

MWLogicalArray

public MWLogicalArray(long val)

Constructs a new scalar logical array that represents the primitive long argument. The value of the array is set to true if the argument is non-zero, and false otherwise.

Parameters:

val - The value to initialize the array with.

MWLogicalArray

public MWLogicalArray(java.lang.Object val)

Constructs a logical array that represents the Object argument. Valid argument types include N-dimensional primitive boolean or numeric arrays, java.lang.Boolean, N-dimensional arrays of java.lang.Boolean, any sub-class of java.lang.Number, and N-dimensional arrays of java.lang.Number.

Parameters:

val - The value to initialize the array with.

Throws:

java.lang.ArrayStoreException - A non-character or non-String array type was specified.

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 MWLogicalArray instance representing a deep copy of the underlying MATLAB array.

Example: Cloning a Logical Array Object Create a clone of MWLogicalArray object A:

     boolean[][] Adata = {{true, false, false},
                          {false, true, false}};
 
     MWLogicalArray A = new MWLogicalArray(Adata);
 
     Object C = A.clone();
 
     System.out.println("Clone of logical matrix A is:");
     System.out.println(C.toString());
 

When run, the example displays this output:

     Clone of logical matrix A is:
           1   0   0
           0   1   0
 

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 MWLogicalArray instance representing a shared copy of the underlying MATLAB array.

Example: Making a Shared Copy of a Logical Array Object Create a shared copy of MWLogicalArray object A:

     boolean[][] Adata = {{true, false, false},
                          {false, true, false}};
 
     MWLogicalArray A = new MWLogicalArray(Adata);
 
     Object C = A.sharedCopy();
 
     System.out.println("Shared copy of logical matrix A is:");
     System.out.println(C.toString());
 

When run, the example displays this output:

     Shared copy of logical matrix A is:
          1   0   0
          0   1   0
 

set

public void set(int index,
       boolean element)

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

Parameters:

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

Throws:

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

set

public void set(int[] index,
       boolean element)

Replaces the element at the specified 1-based index-array in this array with the specified boolean value.

Parameters:

index - Array of indices specifying the location of the element to replace. The length of the index array must be exactly the number of dimensions of this array. Each element of the index array has the valid range: 1 <= index[i] <= N[i], where N[i] = the size of the ith dimension.

element - New value to replace at index.

Throws:

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

Example: Setting a Value in a Logical Array Get and modify the value at A(2,3):

     boolean[][] Adata = {{true, false, false},
                          {false, true, false}};
 
     MWLogicalArray A = new MWLogicalArray(Adata);
 
     int[] index = {2, 3};
     Object d_out = A.get(index);
     System.out.println("Array element A(2,3) is " +
                         d_out.toString() + "\n");
 
     System.out.println("Setting A(2,3) to true\n");
     A.set(index, true);
 
     d_out = A.get(index);
     System.out.println("Array element A(2,3) is " +
                         d_out.toString() + "\n");
 

When run, the example displays this output:

     Array element A(2,3) is false
 
     Setting A(2,3) to true
 
     Array element A(2,3) is true
 

getBoolean

public boolean getBoolean(int index)

Returns the boolean 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.

Throws:

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

getBoolean

public boolean getBoolean(int[] index)

Returns the boolean at the specified 1-based index-array.

Parameters:

index - Array of indices specifying the location of the requested element. The length of the index array must be exactly the number of dimensions of this array. Each element of the index array has the valid range: 1 <= index[i] <= N[i], where N[i] = the size of the ith dimension.

Returns:

value of the requested element.

Throws:

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

Example: Getting a Boolean Value from a Logical Array

     boolean[][] Adata = {{true, false, false},
                          {false, true, false}};
 
     MWLogicalArray A = new MWLogicalArray(Adata);
 
     int[] index = {2, 2};
     System.out.println("A(2,2) is " + A.getBoolean(index));
 

When run, the example displays this output:

     A(2,2) = true
 

classID

public MWClassID classID()

Returns the MATLAB type of this array.

Returns:

returns MWClassID.LOGICAL for MWLogicalArray.

Example: Getting the Class ID for a Logical Array Object Return the class ID for MWLogicalArray object Adata:

     boolean[][] Adata = {{true, false, false},
                          {false, true, false}};
 
     MWLogicalArray A = new MWLogicalArray(Adata);
 
     System.out.println("Class of A is " + A.classID());
 

When run, the example displays this output:

     Class of A is logical
 

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 MWLogicalArray newInstance(int[] dims)

Constructs a logical array with the specified dimensions. The elements of the array are all initialized to false.

Parameters:

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

Returns:

A new MWLogicalArray with the specified dimensions.

Throws:

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

Example: Constructing a Logical Array Object with newInstance Construct a 1-by-5 logical array using the newInstance method. Note that data in the Java array must be stored in a column-wise order so that it will be in row-wise order in the final MWLogicalArray object.

      boolean[] Adata = { true, true, false, false, true};
      int[] dims = {1, 5};
 
      MWLogicalArray A = MWLogicalArray.newInstance(dims, Adata);
      System.out.println("Array A: " + A.toString());
 

When run, the example displays this output:

      Array A: 1 1 0 0 1
 

newInstance

public static MWLogicalArray newInstance(int[] dims,
                         java.lang.Object data)

Constructs a logical array with the specified dimensions and initializes the array with the supplied data. The input array must be a 1-D array with the data stored in column-major order. Valid types for input arrays are: double[], float[], byte[], short[], int[], long[], boolean[], 1-D arrays of any sub-class of java.lang.Number, and 1-D arrays of java.lang.Boolean. If a numeric type is provided, each non-zero array element is converted to true, and false otherwise.

Parameters:

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

data - Data to initialize the array with.

Returns:

A new MWLogicalArray with the specified dimensions and initialized with the supplied data.

Throws:

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

java.lang.ArrayStoreException - Non-numeric or non-boolean data is supplied.

newSparse

public static MWLogicalArray newSparse(int[] rowindex,
                       int[] colindex,
                       java.lang.Object data,
                       int rows,
                       int cols,
                       int nzmax)

Constructs a sparse logical matrix with the specified number of rows and columns, maximum nonzero elements, and initializes the array with the supplied data. The row and column index arrays are used to construct the sparse array such that S(rowindex(k), columnindex(k)) = rData(k), with space allocated for nzmax nonzeros. Valid types for the input array are: double[], float[], byte[], short[], int[], long[], boolean[], 1-D arrays of any sub-class of java.lang.Number, 1-D arrays of java.lang.Boolean, and 1-D arrays of java.lang.String.

Parameters:

rowindex - Array of 1-based row indeces.

colindex - Array of 1-based column indeces.

data - Data to initialize the real part of the array with.

rows - Number of rows in the matrix.

cols - Number of columns in the matrix.

nzmax - Maximum number of nonzero elements.

Returns:

A new sparse MWLogicalArray with the specified size and initialized with the supplied data.

Throws:

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

java.lang.ArrayStoreException - An incompatable array type or invalid array data was specified.

java.lang.IndexOutOfBoundsException - An invalid row or column index was specified.

Example: Constructing a Sparse Logical Array Object Create a sparse array of logical values using the newSparse method:

     boolean[] Adata = {true, true, false, false, true};
     
     int[] ri = {1, 1, 1, 1, 1};
     int[] ci = {1, 2, 3, 4, 5};
 
     MWLogicalArray A = MWLogicalArray.newSparse(ri, ci, Adata);
 
     System.out.println(A.toString());
 

When run, the example displays this output:

     (1,1) 1
     (1,2) 1
     (1,5) 1
 

newSparse

public static MWLogicalArray newSparse(int[] rowindex,
                       int[] colindex,
                       java.lang.Object data,
                       int rows,
                       int cols)

Constructs a sparse logical matrix with the specified number of rows and columns, and initializes the array with the supplied data. The maximum number of nonzero elements is calculated from rData.length. The row and column index arrays are used to construct the sparse array such that S(rowindex(k), columnindex(k)) = rData(k). Valid types for the input array are: double[], float[], byte[], short[], int[], long[], boolean[], 1-D arrays of any sub-class of java.lang.Number, 1-D arrays of java.lang.Boolean, and 1-D arrays of java.lang.String.

Parameters:

rowindex - Array of 1-based row indeces.

colindex - Array of 1-based column indeces.

data - Data to initialize the real part of the array with.

rows - Number of rows in the matrix.

cols - Number of columns in the matrix.

Returns:

A new sparse MWLogicalArray with the specified size and initialized with the supplied data.

Throws:

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

java.lang.ArrayStoreException - An incompatable array type or invalid array data was specified.

java.lang.IndexOutOfBoundsException - An invalid row or column index was specified.

newSparse

public static MWLogicalArray newSparse(int[] rowindex,
                       int[] colindex,
                       java.lang.Object data)

Constructs a sparse logical matrix with the number of rows = max{rowindex(k)} and the number of columns = max{colindex(k)}, and initializes the array with the supplied data. The maximum number of nonzero elements is calculated from rData.length. The row and column index arrays are used to construct the sparse array such that S(rowindex(k), columnindex(k)) = rData(k). Valid types for the input array are: double[], float[], byte[], short[], int[], long[], boolean[], 1-D arrays of any sub-class of java.lang.Number, 1-D arrays of java.lang.Boolean, and 1-D arrays of java.lang.String.

Parameters:

rowindex - Array of 1-based row indeces.

colindex - Array of 1-based column indeces.

data - Data to initialize the real part of the array with.

Returns:

A new sparse MWLogicalArray with the specified size and initialized with the supplied data.

Throws:

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

java.lang.ArrayStoreException - An incompatable array type or invalid array data was specified.

java.lang.IndexOutOfBoundsException - An invalid row or column index was specified.

newSparse

public static MWLogicalArray newSparse(int rows,
                       int cols,
                       int nzmax)

Constructs a sparse logical matrix with no nonzero elements.

Parameters:

rows - Number of rows in the matrix.

cols - Number of columns in the matrix.

nzmax - Maximum number of nonzero elements.

Returns:

A new sparse MWLogicalArray with the specified size and initialized with the supplied data.

Throws:

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

newSparse

public static MWLogicalArray newSparse(java.lang.Object arr)

Constructs a sparse logical matrix from the supplied full matrix.

Parameters:

arr - Array to convert.

Returns:

A new sparse MWLogicalArray initialized with the supplied data.

Throws:

java.lang.ArrayStoreException - An incompatable array type or invalid array data was specified.

serialize

public byte[] serialize()

Serialize the MATLAB array to a byte array.

Returns:

the serialized MATLAB array data

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

getDimensions

public int[] getDimensions()

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

Specified by:

getDimensions in class MWArray

isEmpty

public boolean isEmpty()

Tests if this array has no elements.

Specified by:

isEmpty in class MWArray

isSparse

public boolean isSparse()

Tests if this array is sparse.

Specified by:

isSparse 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

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

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

get

public java.lang.Object get(int index)

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

Specified by:

get in class MWArray

Parameters:

index - The index of the requested element. Valid range: 1 <= index <= N, where N = total number of elements in the array.

Returns:

Object containing the requested element.

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 index-array in this array.

Specified by:

get in class MWArray

Parameters:

index - Array of indices specifying the location of the requested element. The length of the index array must be exactly the number of dimensions of this array. Each element of the index array has the valid range: 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.

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.

Specified by:

set in class MWArray

Parameters:

index - The index of the element to replace. Valid range: 1 <= index <= N, where N = total number of elements in the array.

element - New element to replace at index.

Throws:

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

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.

Specified by:

set in class MWArray

Parameters:

index - Array of indices specifying the location of the element to replace. The length of the index array must be exactly the number of dimensions of this array. Each element of the index array has the valid range: 1 <= index[i] <= N[i], where N[i] = the size of the ith dimension.

element - New element to replace at index.

Throws:

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

toArray

public java.lang.Object[] toArray()

Returns an array containing a copy of the data in the underlying MATLAB array. The returned array has the same dimensionality as the underlying MATLAB array. The elements of the returned array are converted according to default conversion rules. If the underlying MATLAB array is a complex numeric type, toArray returns the real part. If the underlying array is sparse, a full representation of the array is returned. Care should be taken when calling toArray on a sparse array with large row and column dimensions, as this action may exhaust system memory. If the underlying array is a cell or struct array, toArray is recursively called on each cell.

Specified by:

toArray in class MWArray

Returns:

An array with the same dimensionality of the MATLAB array.

getData

public java.lang.Object getData()

Returns a 1-D array containing a copy of the data in the underlying MATLAB array. The elements of the returned array are converted according to default conversion rules. If the underlying MATLAB array is a complex numeric type, getData returns the real part. If the underlying array is a cell or struct array, toArray is recursively called on each cell.

Specified by:

getData in class MWArray

Returns:

A 1-D array of elements stored in column-wise order. The length of the returned array equals numberOfElements() for a non-sparse array, and numberOfNonZeros() for a sparse array.

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