ptolemy.data
Class ScalarToken

java.lang.Object
  ptolemy.data.Token
      ptolemy.data.ScalarToken

All Implemented Interfaces:

java.io.Serializable, BitwiseOperationToken

Direct Known Subclasses:

BooleanToken, ComplexToken, ConcreteScalarToken, DoubleToken, FixToken, FloatToken, IntToken, LongToken, PetiteToken, ShortToken, UnsignedByteToken

public abstract class ScalarToken
extends Token
implements BitwiseOperationToken

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: ScalarToken.java 57040 2010-01-27 20:52:32Z cxh $

Author:

Yuhong Xiong, Mudit Goel, Steve Neuendorffer

See Also:

Serialized Form

Accepted Rating:

Green (yuhong)

Proposed Rating:

Green (neuendor)

Field Summary

protected int[]

_unitCategoryExponents The unit category exponents.

Fields inherited from class ptolemy.data.Token

NIL

Constructor Summary

ScalarToken()

Method Summary

protected abstract ScalarToken	_absolute() Return a ScalarToken containing the absolute value of the value of this token.
protected abstract ScalarToken	_add(ScalarToken rightArgument) Return a new token whose value is the value of the argument token added to the value of this token.
protected int[]	_addCategoryExponents(ScalarToken token) Add the corresponding unit category exponents.
protected boolean	_areUnitsEqual(ScalarToken scalarToken) Return true if the units of this token are the same as that of the argument token.
protected abstract ScalarToken	_bitwiseAnd(ScalarToken rightArgument) Returns a token representing the bitwise AND of this token and the given token.
protected abstract ScalarToken	_bitwiseNot() Returns a token representing the bitwise NOT of this token.
protected abstract ScalarToken	_bitwiseOr(ScalarToken rightArgument) Returns a token representing the bitwise OR of this token and the given token.
protected abstract ScalarToken	_bitwiseXor(ScalarToken rightArgument) Returns a token representing the bitwise XOR of this token and the given token.
protected int[]	_copyOfCategoryExponents() Return a copy of the unit category exponents array.
protected abstract ScalarToken	_divide(ScalarToken rightArgument) Return a new token whose value is the value of this token divided by the value of the argument token.
private Token	_doAdd(Token rightArgument) Return a new token whose value is the value of the argument Token added to the value of this Token.
private BitwiseOperationToken	_doBitwiseAnd(Token rightArgument)
private BitwiseOperationToken	_doBitwiseOr(Token rightArgument)
private BitwiseOperationToken	_doBitwiseXor(Token rightArgument)
private Token	_doDivide(Token rightArgument) Return a new token whose value is the value of this token divided by the value of the argument token.
private BooleanToken	_doIsCloseTo(Token rightArgument, double epsilon) Test for closeness of the values of this Token and the argument Token.
private BooleanToken	_doIsEqualTo(Token rightArgument) Test for equality of the values of this Token and the argument Token.
private BooleanToken	_doIsLessThan(Token rightArgument) Test for ordering of the values of this Token and the argument Token.
private Token	_doModulo(Token rightArgument) Return a new token whose value is the value of this token modulo the value of the argument token.
private Token	_doMultiply(Token rightArgument) Return a new token whose value is the value of this token multiplied by the value of the argument token.
private Token	_doSubtract(Token rightArgument) Return a new token whose value is the value of the argument token subtracted from the value of this token.
protected abstract BooleanToken	_isCloseTo(ScalarToken rightArgument, double epsilon) Test whether the value of this token is close to the first argument, where "close" means that the distance between them is less than or equal to the second argument.
protected BooleanToken	_isEqualTo(ScalarToken token) Test for equality of the values of this token and the argument.
protected abstract BooleanToken	_isLessThan(ScalarToken rightArgument) Test for ordering of the values of this Token and the argument Token.
protected boolean	_isUnitless() Return true if this token does not have a unit.
protected abstract ScalarToken	_modulo(ScalarToken rightArgument) Return a new token whose value is the value of this token modulo the value of the argument token.
protected abstract ScalarToken	_multiply(ScalarToken rightArgument) Return a new token whose value is the value of this token multiplied by the value of the argument token.
protected abstract ScalarToken	_subtract(ScalarToken rightArgument) Return a new token whose value is the value of the argument token subtracted from the value of this token.
protected int[]	_subtractCategoryExponents(ScalarToken token) Subtract the corresponding unit category exponents of the argument token from that of this token.
ScalarToken	absolute() Return a ScalarToken containing the absolute value of 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.
BitwiseOperationToken	bitwiseAnd(Token rightArgument) Returns a token representing the bitwise AND of this token and the given token.
BitwiseOperationToken	bitwiseNot() Returns a token representing the bitwise NOT of this token.
BitwiseOperationToken	bitwiseOr(Token rightArgument) Returns a token representing the bitwise OR of this token and the given token.
BitwiseOperationToken	bitwiseXor(Token rightArgument) Returns a token representing the bitwise XOR of this token and the given token.
byte	byteValue() Return the value in the token as a byte.
Complex	complexValue() Return the value of this token as a Complex.
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 this token divided into the value of the argument token.
double	doubleValue() Return the value of this token as a double.
FixPoint	fixValue() Return the value of this token as a FixPoint.
float	floatValue() Return the value of this token as a float In this base class, we just throw an exception.
abstract Type	getType() Return the type of this token.
int	intValue() Return the value of this token as an int.
ScalarToken	inUnitsOf(ScalarToken units) Return a scalar token that contains the value of this token in the units of the argument token.
BooleanToken	isCloseTo(Token rightArgument, double epsilon) Test whether the value of this Token is close to the argument Token.
BooleanToken	isEqualTo(Token rightArgument) Test for equality of the values of this Token and the argument Token.
BooleanToken	isGreaterThan(ScalarToken rightArgument) Check whether the value of this token is strictly greater than that of the argument token.
BooleanToken	isLessThan(ScalarToken rightArgument) Check whether the value of this token is strictly less than that of the argument token.
ScalarToken	leftShift(int bits) 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.
ScalarToken	logicalRightShift(int bits) 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.
long	longValue() Return the value of this token as a long integer.
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 this token modulo the value of the argument 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 this token multiplied by the value of the argument token.
ScalarToken	rightShift(int bits) 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.
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.
short	shortValue() Return the value of this token as a short.
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 the argument token subtracted from the value of this token.
java.lang.String	unitsString() Return the string representation of the units of this token.

Methods inherited from class ptolemy.data.Token

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

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.

bitwiseAnd

public BitwiseOperationToken bitwiseAnd(Token rightArgument)
                                 throws IllegalActionException

Returns a token representing the bitwise AND of this token and the given token.

Specified by:

bitwiseAnd in interface BitwiseOperationToken

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

public BitwiseOperationToken bitwiseNot()
                                 throws IllegalActionException

Returns a token representing the bitwise NOT of this token.

Specified by:

bitwiseNot in interface BitwiseOperationToken

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

public BitwiseOperationToken bitwiseOr(Token rightArgument)
                                throws IllegalActionException

Returns a token representing the bitwise OR of this token and the given token.

Specified by:

bitwiseOr in interface BitwiseOperationToken

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

public BitwiseOperationToken bitwiseXor(Token rightArgument)
                                 throws IllegalActionException

Returns a token representing the bitwise XOR of this token and the given token.

Specified by:

bitwiseXor in interface BitwiseOperationToken

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.

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.

complexValue

public Complex complexValue()
                     throws IllegalActionException

Return the value of this token as a Complex. In this base class, we just throw an exception.

Returns:

A Complex

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

fixValue

public FixPoint fixValue()
                  throws IllegalActionException

Return the value of this token as a FixPoint. In this base class, we just throw an exception.

Returns:

A FixPoint

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

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 omited. 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.

_doAdd

private Token _doAdd(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 guaranteed by the caller that the type of the argument is the same as the type of this class and has the same units as this token. The resulting token will also have the same type and units. This method defers to the _add() method that takes a ScalarToken. Derived classes should implement that method instead to provide type-specific operation.

Parameters:

rightArgument - The token to add to this token.

Returns:

A new Token containing the result. If either this token or the argument token is a nil token, then then Token.NIL is returned.

Throws:

IllegalActionException - If this operation is not supported by the derived class.

_doBitwiseAnd

private BitwiseOperationToken _doBitwiseAnd(Token rightArgument)
                                     throws IllegalActionException

Throws:

IllegalActionException

_doBitwiseOr

private BitwiseOperationToken _doBitwiseOr(Token rightArgument)
                                    throws IllegalActionException

Throws:

IllegalActionException

_doBitwiseXor

private BitwiseOperationToken _doBitwiseXor(Token rightArgument)
                                     throws IllegalActionException

Throws:

IllegalActionException

_doDivide

private Token _doDivide(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 guaranteed by the caller that the type of the argument is the same as the type of this class. The resulting token will also have the same type and appropriate units. This method defers to the _divide method that takes a ScalarToken. Derived classes should implement that method instead to provide type-specific operation.

Parameters:

rightArgument - The token to divide this token by.

Returns:

A new Token containing the result. If either this token or the argument token is a nil token, then then Token.NIL is returned.

Throws:

IllegalActionException - If this operation is not supported by the derived class.

_doIsCloseTo

private BooleanToken _doIsCloseTo(Token rightArgument,
                                  double epsilon)
                           throws IllegalActionException

Test for closeness 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 may defer to the _isCloseTo() method that takes a ScalarToken. Derived classes should implement that method instead to provide type-specific operation.

Parameters:

rightArgument - The token with which to test closeness.

Returns:

A BooleanToken which contains the result of the test. If either this token or the argument token is a nil token, then a BooleanToken that contains the value false is returned.

Throws:

IllegalActionException - If the units of the argument are not the same as the units of this token, or the method is not supported by the derived class.

_doIsEqualTo

private BooleanToken _doIsEqualTo(Token rightArgument)
                           throws IllegalActionException

Test for equality of the values of this Token and 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 returns BooleanToken.FALSE if the units of this token and the given token are not identical. This method may defer to the _isEqualTo() method that takes a ScalarToken. Derived classes should implement that method instead to provide type-specific operation.

Parameters:

rightArgument - The token with which to test equality.

Returns:

A BooleanToken which contains the result of the test. If either this token or the argument token is a nil token, then a BooleanToken that contains the value false is returned.

Throws:

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

_doIsLessThan

private BooleanToken _doIsLessThan(Token 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 may defer to the _isLessThan() method that takes a ScalarToken. Derived classes should implement that method instead to provide type-specific operation.

Parameters:

rightArgument - The token with which to test ordering.

Returns:

A BooleanToken which contains the result of the test.

Throws:

IllegalActionException - If the units of the argument are not the same as the units of this token, or the method is not supported by the derived class or if either this token or the argument token is a nil token.

_doModulo

private Token _doModulo(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 guaranteed by the caller that the type of the argument is the same as the type of this class and has the same units as this token. The resulting token will also have the same type and units. This method defers to the _modulo() method that takes a ScalarToken. Derived classes should implement that method instead to provide type-specific operation.

Parameters:

rightArgument - The token to modulo this token by.

Returns:

A new Token containing the result. If either this token or the argument token is a nil token, then then Token.NIL is returned.

Throws:

IllegalActionException - If the units are not compatible, or this operation is not supported by the derived class.

_doMultiply

private Token _doMultiply(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 guaranteed by the caller that the type of the argument is the same as the type of this class. The resulting token will also have the same type and appropriate units. This method defers to the _multiply() method that takes a ScalarToken. Derived classes should implement that method instead to provide type-specific operation.

Parameters:

rightArgument - The token to multiply this token by.

Returns:

A new Token containing the result. If either this token or the argument token is a nil token, then then Token.NIL is returned.

Throws:

IllegalActionException - If this operation is not supported by the derived class.

_doSubtract

private Token _doSubtract(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 guaranteed by the caller that the type of the argument is the same as the type of this class and has the same units as this token. The resulting token will also have the same type and units. This method defers to the _subtract method that takes a ScalarToken. Derived classes should implement that method instead to provide type-specific operation.

Parameters:

rightArgument - The token to subtract from this token.

Returns:

A new Token containing the result. If either this token or the argument token is a nil token, then then Token.NIL is returned.

Throws:

IllegalActionException - If the units are not compatible, or this operation is not supported by the derived class.