Package ptolemy.data

Class 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
    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      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 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.