ptolemy.data
Class ArrayToken

java.lang.Object
  extended byptolemy.data.Token
      extended byptolemy.data.AbstractNotConvertibleToken
          extended byptolemy.data.ArrayToken
All Implemented Interfaces:
java.io.Serializable

public class ArrayToken
extends AbstractNotConvertibleToken

A token that contains an array of tokens. The operations between arrays are defined pointwise, and require that the lengths of the arrays are the same. The elements of the ArrayToken will be converted to the least upper bound of their input types and zero length array tokens cannot be created.

Since:
Ptolemy II 0.4
Version:
$Id: ArrayToken.java,v 1.69.2.1 2004/06/18 00:49:04 cxh Exp $
Author:
Yuhong Xiong, Steve Neuendorffer
See Also:
Serialized Form
Accepted Rating:
Green (cxh)
Proposed Rating:
Green (neuendor)

Constructor Summary
ArrayToken(java.lang.String init)
          Construct an ArrayToken from the specified string.
ArrayToken(Token[] value)
          Construct an ArrayToken with the specified token array.
 
Method Summary
protected  Token _add(Token rightArgument)
          Return a new token whose value is the value of the argument token added to the value of this token.
protected  Token _divide(Token rightArgument)
          Return a new token whose value is the value of this token divided by the value of the argument token.
protected  BooleanToken _isCloseTo(Token token, double epsilon)
          Test whether the value of this token is close to the first argument, where "close" means that the distance between them is less than or equal to the second argument.
protected  BooleanToken _isEqualTo(Token token)
          Return a true-valued token if the argument is equal to this one.
protected  Token _modulo(Token rightArgument)
          Return a new token whose value is the value of this token modulo the value of the argument token.
protected  Token _multiply(Token rightArgument)
          Return a new token whose value is the value of this token multiplied by the value of the argument token.
protected  Token _subtract(Token rightArgument)
          Return a new token whose value is the value of the argument token subtracted from the value of this token.
static byte[] arrayTokenToUnsignedByteArray(ArrayToken dataArrayToken)
          Convert an ArrayToken to an array of unsigned bytes.
 Token[] arrayValue()
          Return an array of tokens populated with the contents of this array token.
 ArrayToken elementAdd(Token token)
          Add the given token to each element of this array.
 ArrayToken elementDivide(Token token)
          Divide each element of this array by the given token.
 ArrayToken elementModulo(Token token)
          Modulo each element of this array by the given token.
 ArrayToken elementMultiply(Token token)
          Multiply each element of this array by the given token.
 ArrayToken elementSubtract(Token token)
          Subtract the given token from each element of this array.
 boolean equals(java.lang.Object object)
          Return true if the class of the argument is ArrayToken and of the same length and the elements are equal to that of this token.
 Token getElement(int index)
          Return the element at the specified index.
 Type getElementType()
          Return the type contained in this ArrayToken.
 Type getType()
          Return the type of this ArrayToken.
 int hashCode()
          Return a hash code value for this token.
 int length()
          Return the length of the contained token array.
 Token one()
          Return a new ArrayToken representing the multiplicative identity.
 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.
static ArrayToken unsignedByteArrayToArrayToken(byte[] dataBytes)
          Take an array of unsigned bytes and convert it to an ArrayToken.
 Token zero()
          Returns a new ArrayToken representing the additive identity.
 
Methods inherited from class ptolemy.data.AbstractNotConvertibleToken
add, addReverse, divide, divideReverse, isCloseTo, isEqualTo, modulo, moduloReverse, multiply, multiplyReverse, notSupportedDifferentClassesMessage, subtract, subtractReverse
 
Methods inherited from class ptolemy.data.Token
isCloseTo, notSupportedConversionMessage, notSupportedIncomparableConversionMessage, notSupportedIncomparableMessage, notSupportedMessage, pow, zeroReturnType
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ArrayToken

public ArrayToken(Token[] value)
           throws IllegalActionException
Construct an ArrayToken with the specified token array. All the tokens in the array must have the same type, otherwise an exception will be thrown. Generally, the type of the array created is determined by the type of the first element in the given array. This class makes a copy of the given array, so the passed array may be reused.

Parameters:
value - An array of tokens.
Throws:
IllegalActionException - If the tokens in the array do not have the same type, or the length of the given array is zero.

ArrayToken

public ArrayToken(java.lang.String init)
           throws IllegalActionException
Construct an ArrayToken from the specified string. The format of the string is a list of comma separated token values that begins with "{" and ends with "}". For example "{1, 2, 3}"

Parameters:
init - A string expression of an array.
Throws:
IllegalActionException - If the string does not contain a parsable array.
Method Detail

arrayTokenToUnsignedByteArray

public static byte[] arrayTokenToUnsignedByteArray(ArrayToken dataArrayToken)
Convert an ArrayToken to an array of unsigned bytes.

Parameters:
dataArrayToken - to be converted to a unsigned byte array.
Returns:
dataBytes the resulting unsigned byte array.

arrayValue

public Token[] arrayValue()
Return an array of tokens populated with the contents of this array token. The returned array is a copy so the caller is free to modify it.

Returns:
An array of tokens.

elementAdd

public ArrayToken elementAdd(Token token)
                      throws IllegalActionException
Add the given token to each element of this array.

Returns:
A new array token.
Throws:
IllegalActionException - If the argument token is not of a type that can be added to an element of this token.

elementDivide

public ArrayToken elementDivide(Token token)
                         throws IllegalActionException
Divide each element of this array by the given token.

Returns:
An array token.
Throws:
IllegalActionException - If the argument token is not of a type that can be divided into an element of this token.

elementModulo

public ArrayToken elementModulo(Token token)
                         throws IllegalActionException
Modulo each element of this array by the given token.

Returns:
An array token.
Throws:
IllegalActionException - If the argument token is not of a type that can be used with modulo.

elementMultiply

public ArrayToken elementMultiply(Token token)
                           throws IllegalActionException
Multiply each element of this array by the given token.

Returns:
An array token.
Throws:
IllegalActionException - If the argument token is not of a type that can be multiplied to an element of this token.

elementSubtract

public ArrayToken elementSubtract(Token token)
                           throws IllegalActionException
Subtract the given token from each element of this array.

Returns:
An array token.
Throws:
IllegalActionException - If the argument token is not of a type that can be subtracted from an element of this token.

equals

public boolean equals(java.lang.Object object)
Return true if the class of the argument is ArrayToken and of the same length and the elements are equal to that of this token. Equality of the contained elements is tested by their equals() method.

Parameters:
object - the object to compare with.
Returns:
True if the argument is an array token of the same length and the elements are equal to that of this token.

getElement

public Token getElement(int index)
Return the element at the specified index.

Parameters:
index - The index of the desired element.
Returns:
The token contained in this array token at the specified index.
Throws:
ArrayIndexOutOfBoundException - If the specified index is outside the range of the token array.

getElementType

public Type getElementType()
Return the type contained in this ArrayToken.

Returns:
A Type.

getType

public Type getType()
Return the type of this ArrayToken.

Overrides:
getType in class Token
Returns:
An ArrayType.

hashCode

public int hashCode()
Return a hash code value for this token. This method returns the hash code of the first element.

Returns:
A hash code value for this token.

length

public int length()
Return the length of the contained token array.

Returns:
The length of the contained token array.

one

public Token one()
          throws IllegalActionException
Return a new ArrayToken representing the multiplicative identity. The returned token contains an array of the same size as the array contained by this token, and each element of the array in the returned token is the multiplicative identity of the corresponding element of this token.

Overrides:
one in class Token
Returns:
An ArrayToken.
Throws:
IllegalActionException - If multiplicative identity is not supported by the element token.

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.

Overrides:
toString in class Token
Returns:
A string beginning with "{" that contains expressions for every element in the array separated by commas, ending with "}".

unsignedByteArrayToArrayToken

public static ArrayToken unsignedByteArrayToArrayToken(byte[] dataBytes)
                                                throws IllegalActionException
Take an array of unsigned bytes and convert it to an ArrayToken.

Parameters:
dataBytes - data to be converted to an ArrayToken.
Returns:
dataArrayToken the resulting ArrayToken.
Throws:
IllegalActionException - If ArrayToken can not be created.

zero

public Token zero()
           throws IllegalActionException
Returns a new ArrayToken representing the additive identity. The returned token contains an array of the same size as the array contained by this token, and each element of the array in the returned token is the additive identity of the corresponding element of this token.

Overrides:
zero in class Token
Returns:
An ArrayToken.
Throws:
IllegalActionException - If additive identity is not supported by an element token.

_add

protected Token _add(Token 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 assumed that this class is the class of the argument.

Specified by:
_add in class AbstractNotConvertibleToken
Parameters:
rightArgument - The token whose value we add to the value of this token.
Returns:
A new array token containing the result.
Throws:
IllegalActionException - If the argument is an ArrayToken of different length, or calling the add method of an element token throws it.

_divide

protected 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. It is assumed that this class is the class of the argument.

Specified by:
_divide in class AbstractNotConvertibleToken
Parameters:
rightArgument - The token to divide this token by
Returns:
A new token containing the result.
Throws:
IllegalActionException - If the argument is an ArrayToken of different length, or calling the divide method of the element token throws it.

_isCloseTo

protected BooleanToken _isCloseTo(Token token,
                                  double epsilon)
                           throws IllegalActionException
Test whether the value of this token is close to the first argument, where "close" means that the distance between them is less than or equal to the second argument. This method only makes sense for tokens where the distance between them is reasonably represented as a double. It is assumed that the argument is an ArrayToken, and the isCloseTo() method of the array elements is used.

Specified by:
_isCloseTo in class AbstractNotConvertibleToken
Parameters:
token - The token to compare to this token.
Returns:
A true-valued token if the first argument is close to this token.
Throws:
IllegalActionException - If the elements do not support this comparison.

_isEqualTo

protected BooleanToken _isEqualTo(Token token)
                           throws IllegalActionException
Return a true-valued token if the argument is equal to this one. The isEqualTo() method of the element tokens is used to make the comparison. It is assumed that the argument is an ArrayToken.

Overrides:
_isEqualTo in class AbstractNotConvertibleToken
Parameters:
token - The token to compare to this token.
Returns:
A true-valued token if the argument is equal.
Throws:
IllegalActionException - If the element types do not support this comparison.

_modulo

protected Token _modulo(Token rightArgument)
                 throws IllegalActionException
Return a new token whose value is the value of this token modulo the value of the argument token. It is assumed that this class is the class of the argument.

Specified by:
_modulo in class AbstractNotConvertibleToken
Parameters:
rightArgument - The token to modulo this token by.
Returns:
A new token containing the result.
Throws:
IllegalActionException - If the argument is an ArrayToken of different length, or calling the modulo method of the element token throws it.

_multiply

protected 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. It is assumed that this class is the class of the argument.

Specified by:
_multiply in class AbstractNotConvertibleToken
Parameters:
rightArgument - The token to multiply this token by.
Returns:
A new token containing the result.
Throws:
IllegalActionException - If the argument is an ArrayToken of different length, or calling the multiply method of the element token throws it.

_subtract

protected 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. It is assumed that this class is the class of the argument.

Specified by:
_subtract in class AbstractNotConvertibleToken
Parameters:
rightArgument - The token to subtract to this token.
Returns:
A new token containing the result.
Throws:
IllegalActionException - If the argument is an ArrayToken of different length, or calling the subtract method of the element token throws it.