ptolemy.data

Class MatrixToken

java.lang.Object

ptolemy.data.Token

ptolemy.data.MatrixToken

Direct Known Subclasses:

BooleanMatrixToken, ComplexMatrixToken, ConcreteMatrixToken, DoubleMatrixToken, FixMatrixToken, IntMatrixToken, LongMatrixToken

public abstract class MatrixToken
extends Token

Abstract base class for tokens that contain a 2-D matrix. This class defines methods for type conversion among different matrix tokens. The implementation in this base class just throws an exception. Derived classes should override those methods where the corresponding conversion can be achieved without loss of information. Derived classes should call _elementIsNil() when they encounter a nil token during construction.

Since:

Ptolemy II 0.2

Version:

$Id: MatrixToken.java 70402 2014-10-23 00:52:20Z cxh $

Author:

Yuhong Xiong, Steve Neuendorffer, contributor: Christopher Brooks

Accepted Rating:

Red (cxh) nil token code

Proposed Rating:

Yellow (cxh)

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.Set	_nils HashSet of nil elements, where each element is the index of the element in _value[] that should be nil.
static int	DO_COPY A constant indicating to constructors that contents of an argument 2-D matrix should be copied.
static int	DO_NOT_COPY A constant indicating to constructors not to copy the contents of an argument 2-D matrix, but instead to just copy the pointer to the matrix.

Fields inherited from class ptolemy.data.Token

NIL

Constructor Summary

Constructors

Constructor and Description
MatrixToken()

Method Summary

Modifier and Type	Method and Description
protected MatrixToken	_add(MatrixToken rightArgument) Return a new token whose value is the value of the argument Token added to the value of this Token.
protected MatrixToken	_addElement(Token rightArgument) Return a new token whose value is the value of the argument Token added to the value of each element of this Token.
protected MatrixToken	_divideElement(Token rightArgument) Return a new token whose elements are the result of dividing the elements of this token by the argument.
protected void	_elementIsNil(int element) Add the element to the _nils Set.
protected BooleanToken	_isCloseTo(MatrixToken token, double distance) Test whether the value of this token is close to the first argument, where "close" means that the distance between their elements is less than or equal to the second argument.
protected BooleanToken	_isEqualTo(MatrixToken rightArgument) Test for equality of the values of this Token and the argument Token.
protected MatrixToken	_moduloElement(Token rightArgument) Return a new token whose elements are the modulo of the elements of this token by the argument.
protected MatrixToken	_multiply(MatrixToken rightArgument) Return a new token whose value is the value of this token multiplied by the value of the argument token.
protected MatrixToken	_multiplyElement(Token rightArgument) Return a new token whose value is the value of this token multiplied by the value of the argument scalar token.
protected MatrixToken	_subtract(MatrixToken rightArgument) Return a new token whose value is the value of the argument token subtracted from the value of this token.
protected MatrixToken	_subtractElement(Token rightArgument) Return a new token whose value is the value of the argument Token subtracted from the value of each element of this Token.
protected MatrixToken	_subtractElementReverse(Token rightArgument) Return a new token whose value is the value of each element of this Token subtracted from the value the argument Token.
Token	add(Token rightArgument) Return a new token whose value is the sum of this token and the argument.
Token	addReverse(Token leftArgument) Return a new token whose value is the sum of this token and the argument.
static MatrixToken	arrayToMatrix(Token[] tokens, int rows, int columns) Create a new instance of a MatrixToken subclass with the given number of rows and columns.
static MatrixToken	arrayToMatrix(Type type, Token[] tokens, int rows, int columns) Create a new instance of a MatrixToken subclass with the given element type and number of rows and columns.
static Type	arrayToMatrixReturnType(Type type1, Type type2, Type type3) Return the (exact) return type of the arrayToMatrix function above.
boolean[][]	booleanMatrix() Return the content of this token as a 2-D boolean matrix.
Complex[][]	complexMatrix() Return a copy of the content of this token as a 2-D Complex matrix.
static MatrixToken	create(Token[] tokens, int rows, int columns) Deprecated. Use arrayToMatrix() instead.
static Token[]	createSequence(Token start, Token increment, int length) Create an array of tokens of the given length.
static Type	createSequenceReturnType(Type type1, Type type2, Type type3) Return the (exact) return type of the createSequence function above.
static Token[]	createTokenSequence(Token start, Token increment, int length) Deprecated. Use createSequence() instead.
MatrixToken	crop(int rowStart, int colStart, int rowSpan, int colSpan) Return a new matrix that is a sub-matrix of this matrix.
static int	determineSequenceLength(ScalarToken start, ScalarToken increment, ScalarToken end) Count the number of tokens differing by the given increment that fit in a range between the given start token and the given end token.
Token	divide(Token rightArgument) Return a new token whose value is the value of this token divided by the value of the argument token.
Token	divideReverse(Token leftArgument) Return a new token whose value is the value of the argument token divided by the value of this token.
double[][]	doubleMatrix() Return the content of this token as a 2-D double matrix.
FixPoint[][]	fixMatrix() Return the content of this token as a 2-D fixed point matrix.
abstract int	getColumnCount() Return the number of columns of the matrix.
abstract Token	getElementAsToken(int row, int column) Return the element of the matrix at the specified row and column wrapped in a token.
abstract Type	getElementType() Return the Type of the tokens contained in this matrix token.
abstract int	getRowCount() Return the number of rows of the matrix.
int[][]	intMatrix() Return the content of this token as a 2-D integer matrix.
BooleanToken	isCloseTo(Token rightArgument, double epsilon) Test whether the value of this Token is close to the argument Token.
BooleanToken	isEqualTo(Token rightArgument) Test for equality of the values of this Token and the argument Token.
MatrixToken	join(MatrixToken[][] matrices) Join a matrix of matrices into a single matrix by tiling.
long[][]	longMatrix() Return the content of this matrix as a 2-D long matrix.
static ArrayToken	matrixToArray(MatrixToken matrix) Create a new instance of ArrayToken that contains the values in the specified matrix.
static Type	matrixToArrayReturnType(Type type) Return the (exact) return type of the toArray function above.
Token	modulo(Token rightArgument) Return a new token whose value is this token modulo the value of the argument token.
Token	moduloReverse(Token leftArgument) Return a new token whose value is the value of the argument token modulo the value of this token.
Token	multiply(Token rightArgument) Return a new token whose value is the value of this token multiplied by the value of the argument token.
Token	multiplyReverse(Token leftArgument) Return a new token whose value is the value of the argument token multiplied by the value of this token.
Token	oneRight() Return a new Token representing the right multiplicative identity.
MatrixToken[][]	split(int[] rows, int[] columns) Split this matrix into multiple matrices.
Token	subtract(Token rightArgument) Return a new token whose value is the value of the argument token subtracted from the value of this token.
Token	subtractReverse(Token leftArgument) Return a new token whose value is the value of this token subtracted from the value of the argument token.
ArrayToken	toArray() Return an ArrayToken containing the all the values of this matrix token.
ArrayToken	toArrayColumnMajor() Return an ArrayToken containing the all the values of this matrix token.
static Type	toArrayReturnType(Type type) Return the (exact) return type of the toArray function above.
java.lang.String	toString() Return the value of this token as a string that can be parsed by the expression language to recover a token with the same value.

Methods inherited from class ptolemy.data.Token

getType, isCloseTo, isNil, notSupportedConversionMessage, notSupportedIncomparableConversionMessage, notSupportedIncomparableMessage, notSupportedMessage, notSupportedNullNilStringMessage, one, pow, zero, zeroReturnType

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DO_COPY

public static final int DO_COPY

A constant indicating to constructors that contents of an argument 2-D matrix should be copied. The contents of the input 2-D matrix may be modified after construction without violating the immutability of MatrixTokens.

See Also:

Constant Field Values

DO_NOT_COPY

public static final int DO_NOT_COPY

A constant indicating to constructors not to copy the contents of an argument 2-D matrix, but instead to just copy the pointer to the matrix. The contents of the input 2-D matrix should NOT be modified after construction of an instance of MatrixToken, if the property of immutability is to be preserved.

See Also:

Constant Field Values

_nils

protected java.util.Set _nils

HashSet of nil elements, where each element is the index of the element in _value[] that should be nil.

Constructor Detail

MatrixToken

public MatrixToken()

Method Detail

add

public Token add(Token rightArgument)
          throws IllegalActionException

Return a new token whose value is the sum of this token and the argument. Type conversion also occurs here, so that the operation is performed at the least type necessary to ensure precision. The returned type is the same as the type chosen for the operation. Generally, this is higher of the type of this token and the argument type. Subclasses should not generally override this method, but override the protected _add() method to ensure that type conversion is performed consistently.

Overrides:

add in class Token

Parameters:

rightArgument - The token to add to this token.

Returns:

A new token containing the result.

Throws:

IllegalActionException - If the argument token and this token are of incomparable types, or the operation does not make sense for the given types.

addReverse

public Token addReverse(Token leftArgument)
                 throws IllegalActionException

Return a new token whose value is the sum of this token and the argument. Type resolution also occurs here, with the returned token type chosen to achieve a lossless conversion.

Overrides:

addReverse in class Token

Parameters:

leftArgument - The token to add this token to.

Returns:

A new token containing the result.

Throws:

IllegalActionException - If the argument token is not of a type that can be added to this token, or the units of this token and the argument token are not the same.

arrayToMatrix

public static MatrixToken arrayToMatrix(Token[] tokens,
                                        int rows,
                                        int columns)
                                 throws IllegalActionException

Create a new instance of a MatrixToken subclass with the given number of rows and columns. The token will contain all of the elements of the given array. The element type of the matrix token will be the least upper bound of the types of all of the tokens in the given array. The size of the array must be (rows*columns).

Parameters:

tokens - an array of Token objects

rows - The number of rows.

columns - The number of columns.

Returns:

An instance of a subclass of MatrixToken.

Throws:

IllegalActionException - If no type exists for the matrix token, or the array of tokens is not the right size, or the array is null.

arrayToMatrix

public static MatrixToken arrayToMatrix(Type type,
                                        Token[] tokens,
                                        int rows,
                                        int columns)
                                 throws IllegalActionException

Create a new instance of a MatrixToken subclass with the given element type and number of rows and columns. The token will contain all of the elements of the given array. The size of the array must be (rows*columns).

Parameters:

type - The type of the MatrixToken.

tokens - an array of Token objects

rows - The number of rows.

columns - The number of columns.

Returns:

An instance of a subclass of MatrixToken.

Throws:

IllegalActionException - If the type is not possible, or the array of tokens is not the right size, or the array is null.

arrayToMatrixReturnType

public static Type arrayToMatrixReturnType(Type type1,
                                           Type type2,
                                           Type type3)
                                    throws IllegalActionException

Return the (exact) return type of the arrayToMatrix function above. If the first argument type is an array type, then return a matrix type of the same element type, otherwise return BaseType.UNKNOWN.

Parameters:

type1 - The type of the first argument to the corresponding function.

type2 - The type of the second argument to the corresponding function.

type3 - The type of the third argument to the corresponding function.

Returns:

The type of the value returned from the corresponding function.

Throws:

IllegalActionException - If thrown while getting the matrix type for type1.

booleanMatrix

public boolean[][] booleanMatrix()
                          throws IllegalActionException

Return the content of this token as a 2-D boolean matrix. In this base class, just throw an exception.

Returns:

A 2-D boolean matrix.

Throws:

IllegalActionException - If the token cannot be represented as requested (always thrown in this base class).

complexMatrix

public Complex[][] complexMatrix()
                          throws IllegalActionException

Return a copy of the content of this token as a 2-D Complex matrix. In this base class, just throw an exception.

Returns:

A 2-D Complex matrix.

Throws:

IllegalActionException - If the token cannot be represented as requested (always thrown in this base class).

create

@Deprecated
public static MatrixToken create(Token[] tokens,
                                             int rows,
                                             int columns)
                                      throws IllegalActionException

Deprecated. Use arrayToMatrix() instead.

Create a new instance of a MatrixToken subclass with the given number of rows and columns. The token will contain all of the elements of the given array. The element type of the matrix token will be the least upper bound of the types of all of the tokens in the given array. The size of the array must be (rows*columns).

Parameters:

tokens - an array of Token objects.

rows - The number of rows.

columns - The number of columns.

Returns:

An instance of a subclass of MatrixToken.

Throws:

IllegalActionException - If no type exists for the matrix token, or the array of tokens is not the right size, or the array is null.

createSequence

public static Token[] createSequence(Token start,
                                     Token increment,
                                     int length)
                              throws IllegalActionException

Create an array of tokens of the given length. The first token in the sequence will have value start and each succeeding token will have the value created by adding the given increment to the preceding token.

Parameters:

start - The value of the first element of the returned array.

increment - The difference between elements in the array.

length - The size of the array to create, which must not be negative.

Returns:

An array of tokens of the given length.

Throws:

IllegalActionException - If the length is negative, or tokens of the given type cannot be added together.

createSequenceReturnType

public static Type createSequenceReturnType(Type type1,
                                            Type type2,
                                            Type type3)
                                     throws IllegalActionException

Return the (exact) return type of the createSequence function above. The return type is an array type whose element type is the least upper bound of the first two types.

Parameters:

type1 - The type of the first argument to the corresponding function.

type2 - The type of the second argument to the corresponding function.

type3 - The type of the third argument to the corresponding function.

Returns:

The type of the value returned from the corresponding function.

Throws:

IllegalActionException - If thrown while creating a new ArrayType object.

createTokenSequence

@Deprecated
public static Token[] createTokenSequence(Token start,
                                                      Token increment,
                                                      int length)
                                               throws IllegalActionException

Deprecated. Use createSequence() instead.

Create an array of tokens of the given length. The first token in the sequence will have value start and each succeeding token will have the value created by adding the given increment to the preceding token.

Parameters:

start - The value of the first element of the returned array.

increment - The difference between elements in the array.

length - The size of the array to create, which must not be negative.

Returns:

an array of tokens.

Throws:

IllegalActionException - If the length is negative, or tokens of the given type cannot be added together.

crop

public MatrixToken crop(int rowStart,
                        int colStart,
                        int rowSpan,
                        int colSpan)
                 throws IllegalActionException

Return a new matrix that is a sub-matrix of this matrix.

Parameters:

rowStart - The row to start on.

colStart - The column to start on.

rowSpan - The number of rows to copy.

colSpan - The number of columns to copy.

Returns:

subclasses return a sub-matrix of this matrix. This base class does not return, it always throws an exception.

Throws:

IllegalActionException - If the operation is not supported. Always thrown in this base class.

determineSequenceLength

public static int determineSequenceLength(ScalarToken start,
                                          ScalarToken increment,
                                          ScalarToken end)
                                   throws IllegalActionException

Count the number of tokens differing by the given increment that fit in a range between the given start token and the given end token. This computes, type polymorphically, the value floor(((end-start)/increment) + 1). If the size of the sequence cannot be determined, because the increment is zero, or the increment is positive and end is greater than start, or the increment is negative and start is greater than end, then an exception will be thrown.

Parameters:

start - The given start token.

increment - The increment.

end - The given end token

Returns:

The size of the sequence, which will be greater than zero.

Throws:

IllegalActionException - If the length of the sequence cannot be determined, or the tokens provided do not support the zero, isEqualTo, isLessThan, add, divide, or subtract operations, or is not convertible to a double token.

divide

public final Token divide(Token rightArgument)
                   throws IllegalActionException

Return a new token whose value is the value of this token divided by the value of the argument token. Division is not supported for matrices, so this throws an exception if the argument is a matrix. However, if it is a scalar, then division is performed elementwise.

Overrides:

divide in class Token

Parameters:

rightArgument - The token that divides this token.

Returns:

A new token containing the result.

Throws:

IllegalActionException - If the operation does not make sense for the given types.

divideReverse

public Token divideReverse(Token leftArgument)
                    throws IllegalActionException

Return a new token whose value is the value of the argument token divided by the value of this token. Division is not supported for matrices, so this always throws an exception.

Overrides:

divideReverse in class Token

Parameters:

leftArgument - The token to be divided by the value of this token.

Returns:

A new token containing the result.

Throws:

IllegalActionException - If the argument token and this token are of incomparable types, or the operation does not make sense for the given types.

doubleMatrix

public double[][] doubleMatrix()
                        throws IllegalActionException

Return the content of this token as a 2-D double matrix. In this base class, just throw an exception.

Returns:

A 2-D double matrix.

Throws:

IllegalActionException - If the token cannot be represented as requested (always thrown in this base class).

fixMatrix

public FixPoint[][] fixMatrix()
                       throws IllegalActionException

Return the content of this token as a 2-D fixed point matrix. In this base class, just throw an exception.

Returns:

A 2-D fix matrix.

Throws:

IllegalActionException - If the token cannot be represented as requested (always thrown in this base class).

getColumnCount

public abstract int getColumnCount()

Return the number of columns of the matrix.

Returns:

The number of columns of the matrix.

getElementAsToken

public abstract Token getElementAsToken(int row,
                                        int column)
                                 throws java.lang.ArrayIndexOutOfBoundsException

Return the element of the matrix at the specified row and column wrapped in a token.

Parameters:

row - The row index of the desired element.

column - The column index of the desired element.

Returns:

A token containing the matrix element.

Throws:

java.lang.ArrayIndexOutOfBoundsException - If the specified row or column number is outside the range of the matrix.

getElementType

public abstract Type getElementType()

Return the Type of the tokens contained in this matrix token.

Returns:

A Type.

getRowCount

public abstract int getRowCount()

Return the number of rows of the matrix.

Returns:

The number of rows of the matrix.

intMatrix

public int[][] intMatrix()
                  throws IllegalActionException

Return the content of this token as a 2-D integer matrix. In this base class, just throw an exception.

Returns:

A 2-D integer matrix.

Throws:

IllegalActionException - If the token cannot be represented as requested (always thrown in this base class).

isCloseTo

public final BooleanToken isCloseTo(Token rightArgument,
                                    double epsilon)
                             throws IllegalActionException

Test whether the value of this Token is close to the argument Token. In this base class, we call isEqualTo() and the epsilon argument is ignored. This method should be overridden in derived classes such as DoubleToken and ComplexToken to provide type specific actions for equality testing using the epsilon argument

Overrides:

isCloseTo in class Token

Parameters:

rightArgument - The token to test closeness of this token with.

epsilon - The value that we use to determine whether two tokens are close. In this base class, the epsilon argument is ignored.

Returns:

a boolean token that contains the value true if the value and units of this token are close to those of the argument token.

Throws:

IllegalActionException - If the argument token is not of a type that can be compared with this token.

See Also:

isEqualTo(ptolemy.data.Token)

isEqualTo

public final BooleanToken isEqualTo(Token rightArgument)
                             throws IllegalActionException

Test for equality of the values of this Token and the argument Token. The argument and this token are converted to equivalent types, and then compared. Generally, this is the higher of the type of this token and the argument type. This method defers to the _isEqualTo method to perform a type-specific equality check. Derived classes should override that method to provide type specific actions for equality testing.

Overrides:

isEqualTo in class Token

Parameters:

rightArgument - The token with which to test equality.

Returns:

A BooleanToken which contains the result of the test.

Throws:

IllegalActionException - If this method is not supported by the derived class.

See Also:

isCloseTo(ptolemy.data.Token, double)

join

public MatrixToken join(MatrixToken[][] matrices)
                 throws IllegalActionException

Join a matrix of matrices into a single matrix by tiling. All matrices in the matrix must be of the same type, the same type as this matrix. But none of them needs to actually be this matrix. This base class simply throws an exception. Derived classes provide the implementation. The number of columns in the resulting matrix is the sum of the number of columns in the first row of the argument. The number of rows in the resulting matrix is the sum of the number of rows in the first column of the argument. The matrices are copied into the result starting at the position determined by the first row or column. If the matrices overlap, then while copying left to right, top-to-bottom, data will be overwritten. If there are gaps, the resulting matrix will be filled with zeros.

Parameters:

matrices - A two-dimensional array of matrix tokens.

Returns:

A new matrix token of the same type as the elements in the input matrix of matrix tokens.

Throws:

IllegalActionException - If the types of the matrices in the input are not all the same, or if tiling fails due to size incompatibilities, or if the input matrix has no tokens, or the operation is not supported by this matrix class.

longMatrix

public long[][] longMatrix()
                    throws IllegalActionException

Return the content of this matrix as a 2-D long matrix. In this base class, just throw an exception.

Returns:

A 2-D long matrix.

Throws:

IllegalActionException - If the token cannot be represented as requested (always thrown in this base class).

matrixToArray

public static ArrayToken matrixToArray(MatrixToken matrix)

Create a new instance of ArrayToken that contains the values in the specified matrix.

Parameters:

matrix - The given matrix.

Returns:

An array.

matrixToArrayReturnType

public static Type matrixToArrayReturnType(Type type)

Return the (exact) return type of the toArray function above. If the argument is a matrix type, then return an array type of its element type, otherwise return BaseType.UNKNOWN.

Parameters:

type - The type of the argument to the corresponding function.

Returns:

The type of the value returned from the corresponding function.

modulo

public final Token modulo(Token rightArgument)
                   throws IllegalActionException

Return a new token whose value is this token modulo the value of the argument token.

Overrides:

modulo in class Token

Parameters:

rightArgument - The token that performs modulo on this token.

Returns:

A new token containing the result.

Throws:

IllegalActionException - If the operation does not make sense for the given types.

moduloReverse

public final Token moduloReverse(Token leftArgument)
                          throws IllegalActionException

Return a new token whose value is the value of the argument token modulo the value of this token. Since modulo is not supported for matrices, this always throws an exception.

Overrides:

moduloReverse in class Token

Parameters:

leftArgument - The token to apply modulo to by the value of this token.

Returns:

A new token containing the result.

Throws:

IllegalActionException - If the the operation does not make sense for the given types.

multiply

public final Token multiply(Token rightArgument)
                     throws IllegalActionException

Return a new token whose value is the value of this token multiplied by the value of the argument token. Type conversion also occurs here, so that the operation is performed at the least type necessary to ensure precision. The returned type is the same as the type chosen for the operation. Generally, this is higher of the type of this token and the argument type. This class overrides the base class to perform conversion from scalars to matrices appropriately for matrix multiplication. Subclasses should not generally override this method, but override the protected _multiply() method to ensure that type conversion is performed consistently.

Overrides:

multiply in class Token

Parameters:

rightArgument - The token to multiply this token by.

Returns:

A new token containing the result.

Throws:

IllegalActionException - If the argument token and this token are of incomparable types, or the operation does not make sense for the given types.

multiplyReverse

public final Token multiplyReverse(Token leftArgument)
                            throws IllegalActionException

Return a new token whose value is the value of the argument token multiplied by the value of this token. Type resolution also occurs here, with the returned token type chosen to achieve a lossless conversion.

Overrides:

multiplyReverse in class Token

Parameters:

leftArgument - The token to be multiplied by the value of this token.

Returns:

A new token containing the result.

Throws:

IllegalActionException - If the argument token is not of a type that can be multiplied by this token.

oneRight

public Token oneRight()
               throws IllegalActionException

Return a new Token representing the right multiplicative identity. The returned token contains an identity matrix whose dimensions are the same as the number of columns of the matrix contained in this token. The implementation in this base class just throws an exception. This method should be overridden in the subclass when the right multiplicative identity exists.

Returns:

A new MatrixToken containing the right multiplicative identity.

Throws:

IllegalActionException - If this method is not supported by the derived class.

split

public MatrixToken[][] split(int[] rows,
                             int[] columns)
                      throws IllegalActionException

Split this matrix into multiple matrices. In this base class, this method simply throws an exception. Derived classes provide the implementation.

The matrices are produced from submatrices extracted left-to-right, top-to-bottom, in a raster scan pattern. For example, if rowSplit = {1, 2}, columnSplit = {2, 1}, and the input matrix is as follows:

    1  2  3
    4  5  6
    7  8  9
  

then the first matrix out is a column vector:

    1
    4
  

The second matrix out is

    2  3
    5  6
  

The third is

    7
  

(a 1x1 matrix) and the fourth is

   8  9
  

a row vector. If the input does not have enough elements to fill the specified output matrices, then zeros (of the same type as the input elements) are used. If the input is larger than is required to fill the specified output, then the additional values are discarded.

Parameters:

rows - The number of rows per submatrix.

columns - The number of columns per submatrix.

Returns:

An array of matrix tokens.

Throws:

IllegalActionException - If the operation is not supported.

subtract

public final Token subtract(Token rightArgument)
                     throws IllegalActionException

Return a new token whose value is the value of the argument token subtracted from the value of this token. Type conversion also occurs here, so that the operation is performed at the least type necessary to ensure precision. The returned type is the same as the type chosen for the operation. Generally, this is higher of the type of this token and the argument type. Subclasses should not override this method, but override the protected _subtract() method to ensure that type conversion is performed consistently.

Overrides:

subtract in class Token

Parameters:

rightArgument - The token to subtract from this token.

Returns:

A new token containing the result.

Throws:

IllegalActionException - If the argument token and this token are of incomparable types, or the operation does not make sense for the given types.

subtractReverse

public final Token subtractReverse(Token leftArgument)
                            throws IllegalActionException

Return a new token whose value is the value of this token subtracted from the value of the argument token. Type resolution also occurs here, with the returned token type chosen to achieve a lossless conversion.

Overrides:

subtractReverse in class Token

Parameters:

leftArgument - The token to subtract this token from.

Returns:

A new token containing the result.

Throws:

IllegalActionException - If the argument token is not of a type that can be subtracted to this token, or the units of this token and the argument token are not the same.

toArray

public ArrayToken toArray()

Return an ArrayToken containing the all the values of this matrix token. The type of the tokens in the array is consistent with the type of this token.

Returns:

An ArrayToken containing the elements of this matrix in row-scanned order.

toArrayColumnMajor

public ArrayToken toArrayColumnMajor()

Return an ArrayToken containing the all the values of this matrix token. The type of the tokens in the array is consistent with the type of this token.

Returns:

An ArrayToken containing the elements of this matrix in column-scanned order.

toArrayReturnType

public static Type toArrayReturnType(Type type)

Return the (exact) return type of the toArray function above. If the argument is a matrix type, then return an array type of its element type, otherwise return BaseType.UNKNOWN.

Parameters:

type - The type of the argument to the corresponding function.

Returns:

The type of the value returned from the corresponding function.

toString

public java.lang.String toString()

Return the value of this token as a string that can be parsed by the expression language to recover a token with the same value. The expression starts and ends with a square bracket. The matrix is scanned starting from the upper left and proceeding across each row. Each element in the row is separated by a comma, and the end of a row is represented by a semicolon. The value of each element is obtained using its toString method.

Overrides:

toString in class Token

Returns:

A String representing a matrix similar to Matlab.

_add

protected MatrixToken _add(MatrixToken rightArgument)
                    throws IllegalActionException

Return a new token whose value is the value of the argument Token added to the value of this Token. It is guaranteed by the caller that the type of the argument is the same as the type of this class, and that the matrices have appropriate dimensions. This method should be overridden in derived classes to provide type-specific operation and return a token of the appropriate subclass.

Parameters:

rightArgument - The token to add to this token.

Returns:

A new Token containing the result.

Throws:

IllegalActionException - If this method is not supported by the derived class.

_addElement

protected MatrixToken _addElement(Token rightArgument)
                           throws IllegalActionException

Return a new token whose value is the value of the argument Token added to the value of each element of this Token. It is guaranteed by the caller that the type of the argument is the same as the type of each element of this class.

Parameters:

rightArgument - The token to add to this token.

Returns:

A new Token containing the result.

Throws:

IllegalActionException - If this operation is not supported by the derived class.

_divideElement

protected MatrixToken _divideElement(Token rightArgument)
                              throws IllegalActionException

Return a new token whose elements are the result of dividing the elements of this token by the argument. It is guaranteed by the caller that the type of the argument is the same as the type of each element of this class.

Parameters:

rightArgument - The token that divides this token.

Returns:

A new Token containing the result.

Throws:

IllegalActionException - If this operation is not supported by the derived class.

_isCloseTo

protected BooleanToken _isCloseTo(MatrixToken token,
                                  double distance)
                           throws IllegalActionException

Test whether the value of this token is close to the first argument, where "close" means that the distance between their elements is less than or equal to the second argument. This base class delegates to the token class corresponding to the matrix elements, using its isCloseTo() method. If the two matrices do have the same dimension, then this method returns false.

Parameters:

token - The matrix token to compare to this token.

distance - The specified distance.

Returns:

True if every element of the specified matrix is within the specified distance of the corresponding element of this matrix.

Throws:

IllegalActionException - If a derived class throws it.

_isEqualTo

protected BooleanToken _isEqualTo(MatrixToken rightArgument)
                           throws IllegalActionException

Test for equality of the values of this Token and the argument Token. It is guaranteed by the caller that the type and dimensions of the argument is the same as the type of this class. This method can be overridden in derived classes to provide type-specific operation and return a token of the appropriate subclass. In this base class, this method delegates to equals().

Parameters:

rightArgument - The token to compare to this token.

Returns:

A true-valued token if the argument is equal to this matrix.

Throws:

IllegalActionException - If this method is not supported by a derived class.

_elementIsNil

protected void _elementIsNil(int element)

Add the element to the _nils Set. Subclasses should call this when they encounter a nil token during construction. If _nils is null, this method constructs _nils as a new HashSet.

Parameters:

element - The element index. The format is rows * columnCount + column.

_moduloElement

protected MatrixToken _moduloElement(Token rightArgument)
                              throws IllegalActionException

Return a new token whose elements are the modulo of the elements of this token by the argument. It is guaranteed by the caller that the type of the argument is the same as the type of each element of this class.

Parameters:

rightArgument - The token that performs modulo on this token.

Returns:

A new Token containing the result.

Throws:

IllegalActionException - If this operation is not supported by the derived class.

_multiply

protected MatrixToken _multiply(MatrixToken rightArgument)
                         throws IllegalActionException

Return a new token whose value is the value of this token multiplied by the value of the argument token. It is guaranteed by the caller that the type of the argument is the same as the type of this class, and that the matrices have appropriate dimensions. This method should be overridden in derived classes to provide type-specific operation and return a token of the appropriate subclass.

Parameters:

rightArgument - The token to multiply this token by.

Returns:

A new Token containing the result.

Throws:

IllegalActionException - If this method is not supported by the derived class.

_multiplyElement

protected MatrixToken _multiplyElement(Token rightArgument)
                                throws IllegalActionException

Return a new token whose value is the value of this token multiplied by the value of the argument scalar token. This method should be overridden in derived classes to provide type specific actions for multiply.

Parameters:

rightArgument - The token to multiply this token by.

Returns:

A new Token containing the result that is of the same class as this token.

Throws:

IllegalActionException - If this method is not supported by the derived class.

_subtract

protected MatrixToken _subtract(MatrixToken rightArgument)
                         throws IllegalActionException

Return a new token whose value is the value of the argument token subtracted from the value of this token. It is guaranteed by the caller that the type of the argument is the same as the type of this class, and that the matrices have appropriate dimensions. This method should be overridden in derived classes to provide type-specific operation and return a token of the appropriate subclass.

Parameters:

rightArgument - The token to subtract from this token.

Returns:

A new Token containing the result.

Throws:

IllegalActionException - If this method is not supported by the derived class.

_subtractElement

protected MatrixToken _subtractElement(Token rightArgument)
                                throws IllegalActionException

Return a new token whose value is the value of the argument Token subtracted from the value of each element of this Token. It is guaranteed by the caller that the type of the argument is the same as the type of each element of this class.

Parameters:

rightArgument - The token to subtract from this token.

Returns:

A new Token containing the result.

Throws:

IllegalActionException - If this operation is not supported by the derived class.

_subtractElementReverse

protected MatrixToken _subtractElementReverse(Token rightArgument)
                                       throws IllegalActionException

Return a new token whose value is the value of each element of this Token subtracted from the value the argument Token. It is guaranteed by the caller that the type of the argument is the same as the type of each element of this class.

Parameters:

rightArgument - The token to subtract this token from.

Returns:

A new Token containing the result.

Throws:

IllegalActionException - If this operation is not supported by the derived class.