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: AbstractConvertibleToken.java 70398 2014-10-22 23:44:32Z cxh $

Author:

Steve Neuendorffer

Accepted Rating:
Red

Proposed Rating:
Yellow (neuendor)

Field Summary
- Fields inherited from class ptolemy.data.Token
  NIL

Constructor Summary

Constructors
Constructor and Description

AbstractConvertibleToken()

Constructors
Constructor and Description
`AbstractConvertibleToken()`

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and 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.

Class AbstractConvertibleToken

Field Summary

Fields inherited from class ptolemy.data.Token

Constructor Summary

Method Summary

Methods inherited from class ptolemy.data.Token

Methods inherited from class java.lang.Object

Constructor Detail

AbstractConvertibleToken

Method Detail

add

addReverse

divide

divideReverse

isCloseTo

isEqualTo

modulo

moduloReverse

multiply

multiplyReverse

subtract

subtractReverse

_add

_divide

_isCloseTo

_isEqualTo

_modulo

_multiply

_subtract