Package ptolemy.data

Class AbstractConvertibleToken

java.lang.Object

ptolemy.data.Token

ptolemy.data.AbstractConvertibleToken

Direct Known Subclasses:

DateToken, StringToken

public abstract class AbstractConvertibleToken
extends Token

The Token base class provides a very general interface for building new data types. However, in many ways, the interface is rather complex in order to allow consistent implementation of Token operations that operate on tokens that are defined in different classes. In particular, this requires the duplicate operation and operationReverse methods.

This base class is intended to make it easy to implement tokens that perform operations on other data types. In most (but not all) cases, these operations to be performed only on types that can be losslessly converted to this type (or vice versa). The operations are implemented to first perform the conversion to the same type, and then to perform the operation. This class provides a base class implementation of the operation methods which performs the appropriate conversion, and then defers to a protected _operation method if the type of the argument of the operation is less than or equal to this type. If the argument type is greater than this type, then the appropriate method is called on that type. If the types are incomparable, then this class throws an exception. The protected methods should be overridden in derived classes to provide type-specific operations.

Since:

Ptolemy II 2.1

Version:

$Id$

Author:

Steve Neuendorffer

Pt.AcceptedRating:

Red

Pt.ProposedRating:

Yellow (neuendor)

Field Summary

Fields inherited from class ptolemy.data.Token

NIL

Constructor Summary

Constructors

Constructor	Description
AbstractConvertibleToken()

Method Summary

Modifier and Type	Method	Description
protected abstract 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 abstract 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 abstract BooleanToken	_isCloseTo(Token token, double epsilon)	Test that 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 abstract BooleanToken	_isEqualTo(Token token)	Test for equality of the values of this token and the argument.
protected abstract Token	_modulo(Token rightArgument)	Return a new token whose value is the value of this token modulo the value of the argument token.
protected abstract 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 abstract 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	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.
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.
BooleanToken	isCloseTo(Token token, double epsilon)	Test that 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.
BooleanToken	isEqualTo(Token rightArgument)	Test for equality of the values of this Token and the argument Token.
Token	modulo(Token rightArgument)	Return a new token whose value is the value of 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	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.

Methods inherited from class ptolemy.data.Token

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

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractConvertibleToken

public AbstractConvertibleToken()

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 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:

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 and this token are of incomparable types, or the operation does not make sense for the given types.

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. 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 _divide() method to ensure that type conversion is performed consistently.

Overrides:

divide in class Token

Parameters:

rightArgument - The token to divide into 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.

divideReverse

public final 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. 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 _divide() method to ensure that type conversion is performed consistently.

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.

isCloseTo

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

Test that 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. If the argument token is not of the same type as this token, then either this token or the argument will be converted, if possible, to the type of the other.

Subclasses should not generally override this method, but override the protected _isCloseTo() method to ensure that type conversion is performed consistently.

Overrides:

isCloseTo in class Token

Parameters:

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

epsilon - The value that we use to determine whether two tokens are close.

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 and this token are of incomparable types, or the operation does not make sense for the given types.

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 the argument token and this token are of incomparable types, or the operation does not make sense for the given types.

modulo

public final 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. 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 _modulo() method to ensure that type conversion is performed consistently.

Overrides:

modulo in class Token

Parameters:

rightArgument - The token to divide into 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.

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. 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 _modulo() method to ensure that type conversion is performed consistently.

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 argument token and this token are of incomparable types, or 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. 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 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 _multiply() method to ensure that type conversion is performed consistently.

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 and this token are of incomparable types, or the operation does not make sense for the given types.

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 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:

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 and this token are of incomparable types, or the operation does not make sense for the given types.

_add

protected abstract 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 the type of the argument is the same as the type of this class. This method should be overridden in derived classes to provide type specific actions for add.

Parameters:

rightArgument - The token whose value we add to the value of this token.

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.

_divide

protected abstract 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 the type of the argument is the same as the type of this class. This method should be overridden in derived classes to provide type specific actions for divide.

Parameters:

rightArgument - The token to divide 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.

_isCloseTo

protected abstract BooleanToken _isCloseTo(Token token,
                                           double epsilon)
                                    throws IllegalActionException

Test that 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 type of the argument is the same as the type of this class. This method should be overridden in derived classes to provide type specific actions for the comparison.

Parameters:

token - The token with which to test closeness.

epsilon - The value that we use to determine whether two tokens are close.

Returns:

A token that contains the result of the test.

Throws:

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

_isEqualTo

protected abstract BooleanToken _isEqualTo(Token token)
                                    throws IllegalActionException

Test for equality of the values of this token and the argument. It is assumed that the type of the argument is the same as the type of this class. This method should be overridden in derived classes to provide type specific actions for the comparison.

Parameters:

token - The token with which to test equality.

Returns:

A token that contains the result of the test.

Throws:

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

_modulo

protected abstract 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 the type of the argument is the same as the type of this class. This method should be overridden in derived classes to provide type specific actions for modulo.

Parameters:

rightArgument - The token to modulo 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.

_multiply

protected abstract 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 the type of the argument is the same as the type of this class. 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 abstract 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 the type of the argument is the same as the type of this class. This method should be overridden in derived classes to provide type specific actions for subtract.

Parameters:

rightArgument - The token to subtract from this token.

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.