Package ptolemy.data

Class UnsignedByteToken

  • All Implemented Interfaces:
    BitwiseOperationToken, PartiallyOrderedToken
    public class UnsignedByteToken
extends ScalarToken
    A token that contains a byte number in the range 0 through 255. This UnsignedByteToken definition is in contrast to Java's definition of a byte as a number in the range -128 through 127.

    Overflow and underflow are handled by returning the result of all operations modulo 256. Thus, the result is always in the range 0 through 255. Likewise, constructors of this class generate tokens whose values are the argument modulo 256. Note, for example, that UnsignedByteToken((byte)(-100)) generates a UnsignedByteToken representing the value 156, which is -100 modulo 256.

    Note, also, that the byteValue() method returns a Java byte in the range -128 through 127. This is in contrast to the intValue(), longValue(), doubleValue(), and complexValue() methods which all return values in the range 0 through 255. The value returned by byteValue() is the value represented by the UnsignedByteToken but with 256 subtracted if this value is greater than 127. In other words, the result and the argument are equal modulo 256.

    Since:
    Ptolemy II 2.0
    Version:
    $Id$
    Author:
    Winthrop Williams, Steve Neuendorffer, Contributor: Christopher Hylands
    Pt.AcceptedRating:
    Red (winthrop)
    Pt.ProposedRating:
    Yellow (cxh) ONE, ZERO, nil Token

    • Field Detail

      • NIL

        public static final UnsignedByteToken NIL
        A token that represents a missing value. Null or missing tokens are common in analytical systems like R and SAS where they are used to handle sparsely populated data sources. In database parlance, missing tokens are sometimes called null tokens. Since null is a Java keyword, we use the term "nil". The toString() method on a nil token returns the string "nil".

      • ONE

        public static final UnsignedByteToken ONE
        A UnsignedByteToken with the value 1.

      • ZERO

        public static final UnsignedByteToken ZERO
        A UnsignedByteToken with the value 0.

    • Constructor Detail

      • UnsignedByteToken

        public UnsignedByteToken()
        Construct a token with byte 0.

      • UnsignedByteToken

        public UnsignedByteToken​(byte value)
        Construct a UnsignedByteToken with the specified byte value. The UnsignedByteToken constructed represents a value in the range 0 through 255. However, the byte passed in as the argument to this method represents a value in Java in the range -128 to 127. Due to the difference between these definitions, this method effectively adds 256 if the argument is negative, resulting in a positive value for the UnsignedByteToken.
        Parameters:
        value - The specified value.

      • UnsignedByteToken

        public UnsignedByteToken​(int value)
        Construct a UnsignedByteToken with the specified integer value. The UnsignedByteToken constructed represents a value in the range 0 through 255. However, the integer passed in as the argument to this method represents a value in Java in the range -2^31 to (2^31)-1. This method's cast to (byte) keeps only the low order 8 bits of the integer. This effectively adds or subtracts a multiple of 256 to/from the argument. The resulting UnsignedByteToken falls in the range 0 through 255.
        Parameters:
        value - The specified value.

      • UnsignedByteToken

        public UnsignedByteToken​(java.lang.String init)
                  throws IllegalActionException
        Construct a UnsignedByteToken from the specified string. The string is parsed by the parseByte() method of the Java Byte object.
        Parameters:
        init - The initialization string, which is an integer from 0 to 255. -1 and 256 are illegal values.
        Throws:
        IllegalActionException - If the token could not be created from the given string.

    • Method Detail

      • byteValue

        public byte byteValue()
        Return the value in this token as a byte, modulo 256. The UnsignedByteToken being converted represents a value in the range 0 through 255. However, the Java byte it is being converted to represents a value in the range -128 through 127. Thus, this method has the effect subtracting 256 from the value if the value is greater than 127.
        Overrides:
        byteValue in class ScalarToken
        Returns:
        The byte value contained in this token, modulo 256.

      • complexValue

        public Complex complexValue()
        Return the value of this token as a Complex. The real part of the Complex is the value of this token, the imaginary part is set to 0.
        Overrides:
        complexValue in class ScalarToken
        Returns:
        A Complex.

      • convert

        public static UnsignedByteToken convert​(Token token)
                                 throws IllegalActionException
        Convert the specified token into an instance of UnsignedByteToken. The units of the returned token will be the same as the units of the given token. If the argument is already an instance of UnsignedByteToken, it is returned without any change. If the argument is null or a nil token, then NIL is returned. Otherwise, if the argument is above UnsignedByteToken in the type hierarchy or is incomparable with UnsignedByteToken, an exception is thrown with a message stating that either the conversion is not supported, or the types are incomparable. If none of the above conditions is met, then the argument must be below UnsignedByteToken in the type hierarchy. However, not such types exist at this time, so an exception is thrown with a message stating simply that the conversion is not supported.
        Parameters:
        token - The token to be converted to a UnsignedByteToken.
        Returns:
        A UnsignedByteToken.
        Throws:
        IllegalActionException - If the conversion cannot be carried out.

      • doubleValue

        public double doubleValue()
        Return the value in the token as a double.
        Overrides:
        doubleValue in class ScalarToken
        Returns:
        The value contained in this token as a double.

      • equals

        public boolean equals​(java.lang.Object object)
        Return true if the class of the argument is UnsignedByteToken, and it has the same value as this token.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        object - An instance of Object.
        Returns:
        True if the argument is an instance of UnsignedByteToken with the same value. If either this object or the argument is a nil Token, return false.

      • getType

        public Type getType()
        Return the type of this token.
        Specified by:
        getType in class ScalarToken
        Returns:
        BaseType.UNSIGNED_BYTE

      • hashCode

        public int hashCode()
        Return a hash code value for this token. This method just returns the value of this token.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        A hash code value for this token.

      • intValue

        public int intValue()
        Return the value in the token as an integer.
        Overrides:
        intValue in class ScalarToken
        Returns:
        The byte value contained in this token as a int.

      • isNil

        public boolean isNil()
        Return true if the token is nil, (aka null or missing). Nil or missing tokens occur when a data source is sparsely populated.
        Overrides:
        isNil in class Token
        Returns:
        True if the token is the NIL token.

      • leftShift

        public 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.
        Overrides:
        leftShift in class ScalarToken
        Parameters:
        bits - The number of bits to shift.
        Returns:
        The left shift. If this token is nil, then NIL is returned.

      • logicalRightShift

        public 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. This treats the value as an unsigned number, which may have the effect of destroying the sign of the value.
        Overrides:
        logicalRightShift in class ScalarToken
        Parameters:
        bits - The number of bits to shift.
        Returns:
        The logical right shift. If this token is nil, then NIL is returned.

      • longValue

        public long longValue()
        Return the value in the token as a long.
        Overrides:
        longValue in class ScalarToken
        Returns:
        The byte value contained in this token as a long.

      • one

        public Token one()
        Returns an UnsignedByteToken with value 1.
        Overrides:
        one in class Token
        Returns:
        an UnsignedByteToken with value 1.

      • rightShift

        public 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. This preserves the sign of the result.
        Overrides:
        rightShift in class ScalarToken
        Parameters:
        bits - The number of bits to shift.
        Returns:
        The right shift. If this token is nil, then NIL is returned.

      • shortValue

        public short shortValue()
        Return the value in the token as a short.
        Overrides:
        shortValue in class ScalarToken
        Returns:
        The value contained in this token as a short.

      • toString

        public java.lang.String toString()
        Return the value of this token as a string that can be parsed by the expression language to recover a token with the same value. If this token has a unit, the return string also includes a unit string produced by the unitsString() method in the super class.
        Overrides:
        toString in class Token
        Returns:
        A String representing the byte value and the units (if any) of this token.
        See Also:
        ScalarToken.unitsString()

      • unsignedConvert

        public static short unsignedConvert​(byte value)
        Convert a byte to an integer, treating the byte as an unsigned value in the range 0 through 255. Note that Java defines the byte as having a value ranging from -128 through 127, so 256 is added if this value is negative.
        Parameters:
        value - The byte to convert to an unsigned byte.
        Returns:
        An integer in the range 0 through 255.

      • zero

        public Token zero()
        Returns an UnsignedByteToken with value 0.
        Overrides:
        zero in class Token
        Returns:
        An UnsignedByteToken with value 0.

      • _absolute

        protected 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 is return. Note that it is explicitly allowable to return this token, since the units are the same. Since we have defined the byte as ranging from 0 through 255, its absolute value is equal to itself. Although this method does not actually do anything, it is included to make the UnsignedByteToken interface compatible with the interfaces of the other types.
        Specified by:
        _absolute in class ScalarToken
        Returns:
        An UnsignedByteToken.

      • _add

        protected ScalarToken _add​(ScalarToken rightArgument)
        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 an UnsignedByteToken. Overflow is handled by subtracting 256 so that the resulting sum falls in the range 0 through 255.
        Specified by:
        _add in class ScalarToken
        Parameters:
        rightArgument - The token to add to this token.
        Returns:
        A new UnsignedByteToken containing the result.

      • _bitwiseAnd

        protected ScalarToken _bitwiseAnd​(ScalarToken rightArgument)
        Returns a token representing the bitwise AND of this token and the given token. It is assumed that the type of the argument is UnsignedByteToken.
        Specified by:
        _bitwiseAnd in class ScalarToken
        Parameters:
        rightArgument - The UnsignedByteToken to bitwise AND with this one.
        Returns:
        The bitwise AND.

      • _bitwiseNot

        protected ScalarToken _bitwiseNot()
        Returns a token representing the bitwise NOT of this token.
        Specified by:
        _bitwiseNot in class ScalarToken
        Returns:
        The bitwise NOT of this token.

      • _bitwiseOr

        protected ScalarToken _bitwiseOr​(ScalarToken rightArgument)
        Returns a token representing the bitwise OR of this token and the given token. It is assumed that the type of the argument is UnsignedByteToken.
        Specified by:
        _bitwiseOr in class ScalarToken
        Parameters:
        rightArgument - The UnsignedByteToken to bitwise OR with this one.
        Returns:
        The bitwise OR.

      • _bitwiseXor

        protected ScalarToken _bitwiseXor​(ScalarToken rightArgument)
        Returns a token representing the bitwise XOR of this token and the given token. It is assumed that the type of the argument is UnsignedByteToken.
        Specified by:
        _bitwiseXor in class ScalarToken
        Parameters:
        rightArgument - The UnsignedByteToken to bitwise XOR with this one.
        Returns:
        The bitwise XOR.

      • _divide

        protected ScalarToken _divide​(ScalarToken rightArgument)
        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 an UnsignedByteToken. The result will be a byte containing the quotient. For example, 255 divided by 10 returns 25. This method does not test for or attempt to prevent division by 0.
        Specified by:
        _divide in class ScalarToken
        Parameters:
        rightArgument - The token to divide this token by.
        Returns:
        A new UnsignedByteToken containing the result.

      • _isCloseTo

        protected 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. It is assumed that the argument is an UnsignedByteToken.
        Specified by:
        _isCloseTo in class ScalarToken
        Parameters:
        rightArgument - The token to compare to this token.
        epsilon - The distance.
        Returns:
        A true-valued token if the first argument is close to this token.

      • _isLessThan

        protected BooleanToken _isLessThan​(ScalarToken rightArgument)
        Test for ordering of the values of this Token and the argument Token. It is assumed that the type of the argument is UnsignedByteToken.
        Specified by:
        _isLessThan in class ScalarToken
        Parameters:
        rightArgument - The token to add to this token.
        Returns:
        A new Token containing the result.

      • _modulo

        protected ScalarToken _modulo​(ScalarToken rightArgument)
        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 UnsignedByteToken. This method does not test for or attempt to prevent division by 0.
        Specified by:
        _modulo in class ScalarToken
        Parameters:
        rightArgument - The token to modulo this token by.
        Returns:
        A new UnsignedByteToken containing the result.

      • _multiply

        protected ScalarToken _multiply​(ScalarToken rightArgument)
        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 UnsignedByteToken. Overflow is handled by subtracting the multiple of 256 which puts the result into the range 0 through 255. In other words, return the product modulo 256.
        Specified by:
        _multiply in class ScalarToken
        Parameters:
        rightArgument - The token to multiply this token by.
        Returns:
        A new UnsignedByteToken containing the product modulo 256.

      • _subtract

        protected ScalarToken _subtract​(ScalarToken rightArgument)
        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 UnsignedByteToken. Underflow is handled by adding 256 to the result if it is less than 0. Thus the result is always in the range 0 through 255.
        Specified by:
        _subtract in class ScalarToken
        Parameters:
        rightArgument - The token to subtract from this token.
        Returns:
        A new UnsignedByteToken containing the difference modulo 256.