Package ptolemy.data

Class ScalarToken

  • All Implemented Interfaces:
    BitwiseOperationToken, PartiallyOrderedToken
    Direct Known Subclasses:
    BooleanToken, ComplexToken, ConcreteScalarToken, DoubleToken, FixToken, FloatToken, IntToken, LongToken, PetiteToken, ShortToken, UnsignedByteToken
    public abstract class ScalarToken
extends Token
implements BitwiseOperationToken, PartiallyOrderedToken
    Abstract base class for tokens that contain a scalar. This base class extends the Token class to properly implement type conversion and the units portion of the standard operations for scalar tokens. It also adds methods for querying the natural ordering between scalars.

    This class has a number of protected abstract methods that subclasses must implement. These methods need only implement the numerical portion of the operation between two tokens of the same type. This base class will handle the conversion of tokens from different types to the same type before calling the protected method, and the proper computation of the units of the returned token afterwards.

    In general, any instance of a scalar token may be optionally associated with a set of units. In the arithmetic methods add(), modulo(), and subtract(), the two operands must have the same units. Otherwise, an exception will be thrown. In the methods multiply() and divide(), the units of the resulting token will be computed automatically. IMPORTANT: The protected methods implemented in derived classes are expected to return a new token in the case of multiply and divide. This new token will automatically have its units set correctly by this base class implementation. Certain cases, such as multiplication by one, cannot be optimized to simply return an the input token without performing the multiplication, since the units of the result may be different than the units of either input token.

    Since:
    Ptolemy II 0.2
    Version:
    $Id$
    Author:
    Yuhong Xiong, Mudit Goel, Steve Neuendorffer
    Pt.AcceptedRating:
    Green (yuhong)
    Pt.ProposedRating:
    Green (neuendor)

    • Field Detail

      • _unitCategoryExponents

        protected int[] _unitCategoryExponents
        The unit category exponents. The unit system contains a set of base unit categories and derived categories. The base categories are customizable by the user. For example, the user may choose to use the SI unit system which has 7 base categories: length, mass, time, electric current, thermodynamic temperature, amount of substance, and luminous intensity. The customization is done by defining a MoML file to specify the categories and the units in each category. Each category has an index, assigned by the order the category appears in the MoML file. Derived units are recorded by the exponents of the category. For example, the category speed, which is length/time, is stored by an exponent of 1 for the length category, and an exponent of -1 for the time category. This array records the exponents of the base categories.

    • Constructor Detail

      • ScalarToken

        public ScalarToken()

    • Method Detail

      • absolute

        public final ScalarToken absolute()
        Return a ScalarToken containing the absolute value of the value of this token. If this token contains a non-negative number, it is returned directly; otherwise, a new token is returned. Note that it is explicitly allowable to return this token, since the units are the same. This method defers to the _absolute() method to perform the operation, and derived classes should implement that method to provide type-specific behavior.
        Returns:
        A ScalarToken with the same units, and likely to be of the same type as this token. If this token is a nil token, then Token.NIL is returned.

      • add

        public final 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, which is the higher of the type of this token and the argument type. Subclasses should implement the protected _add() method to perform the correct type-specific operation.
        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 have different units, or the operation does not make sense for the given types.

      • addReverse

        public final 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, which is the higher of the type of this token and the argument type. Subclasses should implement the protected _add() method to perform the correct type-specific operation.
        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 have different units, or the operation does not make sense for the given types.

      • byteValue

        public byte byteValue()
               throws IllegalActionException
        Return the value in the token as a byte. In this base class, we just throw an exception.
        Returns:
        The byte value contained in this token.
        Throws:
        IllegalActionException - Always thrown.

      • 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, which is the higher of the type of this token and the argument type. The returned token will also have the correct units. Subclasses should implement the protected _divide() method to perform the correct type-specific operation.
        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 this token divided into 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, which is the higher of the type of this token and the argument type. The returned token will also have the correct units. Subclasses should implement the protected _divide() method to perform the correct type-specific operation.
        Overrides:
        divideReverse in class Token
        Parameters:
        leftArgument - The token to be divided into 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.

      • doubleValue

        public double doubleValue()
                   throws IllegalActionException
        Return the value of this token as a double. In this base class, we just throw an exception.
        Returns:
        A double
        Throws:
        IllegalActionException - Always thrown

      • floatValue

        public float floatValue()
                 throws IllegalActionException
        Return the value of this token as a float In this base class, we just throw an exception.
        Returns:
        A float
        Throws:
        IllegalActionException - Always thrown

      • getType

        public abstract Type getType()
        Return the type of this token. Subclasses must implement this method to return the correct type.
        Overrides:
        getType in class Token
        Returns:
        BaseType.SCALAR

      • inUnitsOf

        public ScalarToken inUnitsOf​(ScalarToken units)
                      throws IllegalActionException
        Return a scalar token that contains the value of this token in the units of the argument token. The unit category of the argument token must be the same as that of this token, otherwise, an exception will be thrown. The returned token is unitless.
        Parameters:
        units - A scalar token that represents a unit.
        Returns:
        A scalar token that does not have a unit.
        Throws:
        IllegalActionException - If the unit category of the argument token is not the same as that of this one.

      • intValue

        public int intValue()
             throws IllegalActionException
        Return the value of this token as an int. In this base class, we just throw an exception.
        Returns:
        The value of this token as an int.
        Throws:
        IllegalActionException - Always thrown.

      • isCloseTo

        public final BooleanToken isCloseTo​(Token rightArgument,
                                    double epsilon)
                             throws IllegalActionException
        Test whether the value of this Token is close to 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. Subclasses should implement the protected _isCloseTo() method to perform the correct type-specific operation.
        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.
        Returns:
        A boolean token that contains the value true if the units of this token and the argument token are the same, and their values are close.
        Throws:
        IllegalActionException - If the argument token is not of a type that can be compared with this token, or the units are not the same.
        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 implement 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 boolean token that contains the value true if the values and units of this token and the argument token are the same.
        Throws:
        IllegalActionException - If this method is not supported by the derived class.
        See Also:
        isCloseTo(ptolemy.data.Token, double)

      • isGreaterThan

        public final BooleanToken isGreaterThan​(ScalarToken rightArgument)
                                 throws IllegalActionException
        Check whether the value of this token is strictly greater than that of 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 _isLessThan() method to perform a type-specific equality check. Derived classes should implement that method to provide type specific actions for equality testing.
        Parameters:
        rightArgument - The token to compare against.
        Returns:
        A boolean token with value true if this token has the same units as the argument, and is strictly greater than the argument.
        Throws:
        IllegalActionException - If the argument token and this token are of incomparable types, or have different units, or the operation does not make sense for the given types.

      • isLessThan

        public final BooleanToken isLessThan​(PartiallyOrderedToken rightArgument)
                              throws IllegalActionException
        Check whether the value of this token is strictly less than that of the argument token.
        Specified by:
        isLessThan in interface PartiallyOrderedToken
        Parameters:
        rightArgument - The token to compare against.
        Returns:
        A boolean token with value true if this token is strictly less than the argument.
        Throws:
        IllegalActionException - If the argument token and this token are of incomparable types, or have different units, or the operation does not make sense for the given types.

      • isLessThan

        public final BooleanToken isLessThan​(ScalarToken rightArgument)
                              throws IllegalActionException
        Check whether the value of this token is strictly less than that of 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 _isLessThan() method to perform a type-specific equality check. Derived classes should implement that method to provide type specific actions for equality testing.
        Parameters:
        rightArgument - The token to compare against.
        Returns:
        A boolean token with value true if this token has the same units as the argument, and is strictly less than the argument.
        Throws:
        IllegalActionException - If the argument token and this token are of incomparable types, or have different units, or the operation does not make sense for the given types.

      • leftShift

        public ScalarToken leftShift​(int bits)
                      throws IllegalActionException
        Returns a token representing the result of shifting the bits of this token towards the most significant bit, filling the least significant bits with zeros.
        Parameters:
        bits - The number of bits to shift.
        Returns:
        The left shift.
        Throws:
        IllegalActionException - If the given token is not compatible for this operation, or the operation does not make sense for this type.

      • logicalRightShift

        public ScalarToken logicalRightShift​(int bits)
                              throws IllegalActionException
        Returns a token representing the result of shifting the bits of this token towards the least significant bit, filling the most significant bits with zeros. This treats the value as an unsigned number, which may have the effect of destroying the sign of the value.
        Parameters:
        bits - The number of bits to shift.
        Returns:
        The right shift.
        Throws:
        IllegalActionException - If the given token is not compatible for this operation, or the operation does not make sense for this type.

      • longValue

        public long longValue()
               throws IllegalActionException
        Return the value of this token as a long integer. In this base class, we just throw an exception.
        Returns:
        The value of this token as a long.
        Throws:
        IllegalActionException - Always thrown.

      • 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, which is the higher of the type of this token and the argument type. Subclasses should implement the protected _modulo() method to perform the correct type-specific operation.
        Overrides:
        modulo in class Token
        Parameters:
        rightArgument - The token to modulo with this token.
        Returns:
        A new token containing the result.
        Throws:
        IllegalActionException - If the argument token and this token are of incomparable types, or have different units, 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 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, which is the higher of the type of this token and the argument type. Subclasses should implement the protected _modulo() method to perform the correct type-specific operation.
        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 have different units, 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, which is the higher of the type of this token and the argument type. Subclasses should implement the protected _multiply() method to perform the correct type-specific operation.
        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 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, which is the higher of the type of this token and the argument type. Subclasses should implement the protected _multiply() method to perform the correct type-specific operation.
        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.

      • rightShift

        public ScalarToken rightShift​(int bits)
                       throws IllegalActionException
        Returns a token representing the result of shifting the bits of this token towards the least significant bit, filling the most significant bits with the sign of the value. This preserves the sign of the result.
        Parameters:
        bits - The number of bits to shift.
        Returns:
        The right shift.
        Throws:
        IllegalActionException - If the given token is not compatible for this operation, or the operation does not make sense for this type.

      • setUnitCategory

        @Deprecated
public void setUnitCategory​(int index)
        Deprecated.
        We need a better way of manufacturing the tokens for base units, since this method violates the immutability of tokens.
        Set the unit category this token belongs to. This method is called from within the units system to create tokens representing base units. This method should not be called by user code.
        Parameters:
        index - The unit category index.

      • shortValue

        public short shortValue()
                 throws IllegalActionException
        Return the value of this token as a short. In this base class, we just throw an exception.
        Returns:
        A short
        Throws:
        IllegalActionException - Always thrown

      • 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, which is the higher of the type of this token and the argument type. Subclasses should implement the protected _subtract() method to perform the correct type-specific operation.
        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 have different units, 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 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, which is the higher of the type of this token and the argument type. Subclasses should implement the protected _subtract() method to perform the correct type-specific operation.
        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 have different units, or the operation does not make sense for the given types.

      • unitsString

        public java.lang.String unitsString()
        Return the string representation of the units of this token. The general format of the returned string is "(l_1 * l_2 * ... * l_m) / (s_1 * s_2 * ... * s_n)". For example: "(meter * kilogram) / (second * second)". If m or n is 1, then the parenthesis above or below "/" is omitted. For example: "meter / second". If there is no term above "/", the format becomes "1 / (s_1 * s_2 * ... * s_n)". For example: "1 / meter". If this token does not have a unit, return an empty string.
        Returns:
        A string representation of the units of this token.

      • _absolute

        protected abstract ScalarToken _absolute()
        Return a ScalarToken containing the absolute value of the value of this token. If this token contains a non-negative number, it is returned directly; otherwise, a new token is returned. Note that it is explicitly allowable to return this token, since the units are the same. Derived classes must implement this method in a type-specific fashion.
        Returns:
        A ScalarToken, which is likely, but not required to be the same type as this token.

      • _add

        protected abstract ScalarToken _add​(ScalarToken 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. 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.

      • _addCategoryExponents

        protected int[] _addCategoryExponents​(ScalarToken token)
        Add the corresponding unit category exponents.
        Parameters:
        token - A token whose exponent will be added with the exponents of this token.
        Returns:
        An int array containing the addition result, or null if the result is unitless.

      • _areUnitsEqual

        protected boolean _areUnitsEqual​(ScalarToken scalarToken)
        Return true if the units of this token are the same as that of the argument token. If both tokens do not have units, return true.
        Parameters:
        scalarToken - A scalar token.
        Returns:
        True if the units of this token is the same as that of the argument token; false otherwise.

      • _bitwiseAnd

        protected abstract ScalarToken _bitwiseAnd​(ScalarToken rightArgument)
                                    throws IllegalActionException
        Returns a token representing the bitwise AND of this token and the given token.
        Parameters:
        rightArgument - The ScalarToken to bitwise AND with this one.
        Returns:
        The bitwise AND.
        Throws:
        IllegalActionException - If the given token is not compatible for this operation, or the operation does not make sense for this type.

      • _bitwiseNot

        protected abstract ScalarToken _bitwiseNot()
                                    throws IllegalActionException
        Returns a token representing the bitwise NOT of this token.
        Returns:
        The bitwise NOT of this token.
        Throws:
        IllegalActionException - If the given token is not compatible for this operation, or the operation does not make sense for this type.

      • _bitwiseOr

        protected abstract ScalarToken _bitwiseOr​(ScalarToken rightArgument)
                                   throws IllegalActionException
        Returns a token representing the bitwise OR of this token and the given token.
        Parameters:
        rightArgument - The ScalarToken to bitwise OR with this one.
        Returns:
        The bitwise OR.
        Throws:
        IllegalActionException - If the given token is not compatible for this operation, or the operation does not make sense for this type.

      • _bitwiseXor

        protected abstract ScalarToken _bitwiseXor​(ScalarToken rightArgument)
                                    throws IllegalActionException
        Returns a token representing the bitwise XOR of this token and the given token.
        Parameters:
        rightArgument - The ScalarToken to bitwise XOR with this one.
        Returns:
        The bitwise XOR.
        Throws:
        IllegalActionException - If the given token is not compatible for this operation, or the operation does not make sense for this type.

      • _copyOfCategoryExponents

        protected int[] _copyOfCategoryExponents()
        Return a copy of the unit category exponents array. If this token does not have a unit, return null;
        Returns:
        An int array that is a copy of the unit category exponents of this token.

      • _divide

        protected abstract ScalarToken _divide​(ScalarToken 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 guaranteed by the caller 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 operation and return a token of the appropriate subclass.
        Parameters:
        rightArgument - The token to divide this token by.
        Returns:
        A new Token containing the result.
        Throws:
        IllegalActionException - If this method is not supported by the derived class.

      • _isCloseTo

        protected abstract BooleanToken _isCloseTo​(ScalarToken rightArgument,
                                           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.
        Parameters:
        rightArgument - The token to compare to this token.
        epsilon - The value that we use to determine whether two tokens are close.
        Returns:
        A token containing true if the value of the first argument is close to the value of this token.
        Throws:
        IllegalActionException - If there is a problem processing the rightArgument.

      • _isEqualTo

        protected BooleanToken _isEqualTo​(ScalarToken token)
                           throws IllegalActionException
        Test for equality of the values of this token and the argument. This base class delegates to the equals() method.
        Parameters:
        token - The token to compare to this token.
        Returns:
        A token containing true if the value element of the first argument is equal to the value of this token.
        Throws:
        IllegalActionException - Not thrown in this base class.

      • _isLessThan

        protected abstract BooleanToken _isLessThan​(ScalarToken rightArgument)
                                     throws IllegalActionException
        Test for ordering of the values of this Token and the argument Token. It is guaranteed by the caller that the type and units of the argument is the same as the type of this class. 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.

      • _isUnitless

        protected boolean _isUnitless()
        Return true if this token does not have a unit.
        Returns:
        True if this token does not have a unit.

      • _modulo

        protected abstract ScalarToken _modulo​(ScalarToken rightArgument)
                                throws IllegalActionException
        Return a new token whose value is the value of this token modulo 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. 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 modulo this token by.
        Returns:
        A new Token containing the result.
        Throws:
        IllegalActionException - If this method is not supported by the derived class.

      • _multiply

        protected abstract ScalarToken _multiply​(ScalarToken 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. 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.

      • _subtract

        protected abstract ScalarToken _subtract​(ScalarToken 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. 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.

      • _subtractCategoryExponents

        protected int[] _subtractCategoryExponents​(ScalarToken token)
        Subtract the corresponding unit category exponents of the argument token from that of this token.
        Parameters:
        token - A token whose exponent will be subtracted from the exponents of this token.
        Returns:
        An array of int containing the result, or null if the result is unitless.