edu.princeton.toy.lang
Class TWord

java.lang.Object
  extended by edu.princeton.toy.lang.TWord

public class TWord
extends Object

TWord is the primitive value which toy registers and memory can take. TWord is immutable, like java.lang.String, which means that classes can return TWords without being concerned with wheter or not the recipient will change the value. The immutable feature allows us to keep track of and reuse TWord CACHED_REFERENCES to save memory allocation overhead.

CACHED_REFERENCES of TWord are slightly different than short primitives in that they can take on a special value, UNINITIALIZED_VALUE, which is identical to getWord(0) except for two things:


Field Summary
static int BIT_COUNT
          The number of bits a TWord would take.
static char[] HEX_DIGITS
          An array to convert an integer between 0 and 16 to a hexidecimal digit.
static String[] HEX_PAIRS
          An array to convert an integer between 0 and 256 to a pair of hexidecimal digit.
static TWord MAX_VALUE
          The maximum value a TWord can take.
static TWord MIN_VALUE
          The minimum value a TWord can take.
static TWord ONE
          A constant for getWord((short)0).
static TWord UNINITIALIZED_VALUE
          The uninitialized value is identical to getWord(0) with the following exceptions: The isInitialized() method returns false in UNINITIALIZED_VALUE but not in getWord(0).
static TWord ZERO
          A constant for getWord((short)0).
 
Method Summary
static TWord add(TWord a, TWord b, TExceptionHandler exceptionHandler)
          Implements the addition operator for the TWord type.
static TWord and(TWord a, TWord b, TExceptionHandler exceptionHandler)
          Implements the bitwise-and operator for the TWord type.
 boolean equals(Object obj)
          Evaluates wheter or not two TWords have the same values.
 byte getD()
          Returns the second leftmost/most-significant four bits of the TWord.
 short getImm()
          Returns the rightmost/least-significant eight bits of the TWord.
 byte getOp()
          Returns the leftmost/most-significant four bits of the TWord.
 byte getS()
          Returns the third leftmost/most-significant four bits of the TWord.
 byte getT()
          Returns the rightmost/least-significant four bits of the TWord.
 short getValue()
          Returns the short primitive to which this TWord corresponds.
static TWord getWord(short value)
          Returns a TWord initialize to the given value.
static int hexDigitToInt(char c)
          Returns the hexidecimal value of a character.
 TWord initializedValue()
          Returns the initialized equivalent of this word.
static boolean isHexDigit(char c)
          Returns whether or not a character is a hexidecimal digit.
 boolean isInitialized()
          Returns wheter or not this word has been defined yet.
static TWord leftShift(TWord a, TWord b, TExceptionHandler exceptionHandler)
          Implements the logical-left-shift operator for the TWord type.
static TWord parseWord(String string, int radix)
          Parses a TWord from a string.
static TWord rightShift(TWord a, TWord b, TExceptionHandler exceptionHandler)
          Implements the arithmatic-right-shift operator for the TWord type.
static TWord subtract(TWord a, TWord b, TExceptionHandler exceptionHandler)
          Implements the subtraction operator for the TWord type.
 String toBinaryString(boolean distinguishUninitialized)
          Returns the binary representation of this TWord.
 String toDecimalString(boolean distinguishUninitialized)
          Returns the decimal representation of this TWord.
 String toFormattedBinaryString(boolean distinguishUninitialized)
          Returns the formatted binary representation of this TWord in which every four bits are separated by a space.
 String toHexString(boolean distinguishUninitialized)
          Returns the hexidecimal representation of this TWord.
 String toPseudoCodeString(boolean distinguishUninitialized)
          Returns the pseudo-code form of the TWord.
 String toString()
          Returns the detailed representation of this TWord.
 String toString(boolean distinguishUninitialized)
          Returns the detailed representation of this TWord.
static TWord xor(TWord a, TWord b, TExceptionHandler exceptionHandler)
          Implements the bitwise-xor operator for the TWord type.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

BIT_COUNT

public static final int BIT_COUNT
The number of bits a TWord would take.

See Also:
Constant Field Values

HEX_DIGITS

public static final char[] HEX_DIGITS
An array to convert an integer between 0 and 16 to a hexidecimal digit.


HEX_PAIRS

public static final String[] HEX_PAIRS
An array to convert an integer between 0 and 256 to a pair of hexidecimal digit.


UNINITIALIZED_VALUE

public static final TWord UNINITIALIZED_VALUE
The uninitialized value is identical to getWord(0) with the following exceptions:


MIN_VALUE

public static final TWord MIN_VALUE
The minimum value a TWord can take.


MAX_VALUE

public static final TWord MAX_VALUE
The maximum value a TWord can take.


ZERO

public static final TWord ZERO
A constant for getWord((short)0).


ONE

public static final TWord ONE
A constant for getWord((short)0).

Method Detail

isInitialized

public boolean isInitialized()
Returns wheter or not this word has been defined yet.

Returns:
True iff this word is not UNINITIALIZED_VALUE.

getValue

public short getValue()
Returns the short primitive to which this TWord corresponds.

Returns:
The value of this TWord. Note that both getWord(0) and UNINITIALIZED_VALUE have the same value.

getOp

public byte getOp()
Returns the leftmost/most-significant four bits of the TWord.

Returns:
(byte)((getValue() >> 12) & 0xF)

getD

public byte getD()
Returns the second leftmost/most-significant four bits of the TWord.

Returns:
(byte)((getValue() >> 8) & 0xF)

getS

public byte getS()
Returns the third leftmost/most-significant four bits of the TWord.

Returns:
(byte)((getValue() >> 4) & 0xF)

getT

public byte getT()
Returns the rightmost/least-significant four bits of the TWord.

Returns:
(byte)(getValue() & 0xF)

initializedValue

public TWord initializedValue()
Returns the initialized equivalent of this word.

Returns:
The initialized equivalent of this word.

getImm

public short getImm()
Returns the rightmost/least-significant eight bits of the TWord.

Returns:
(short)(getValue() & 0xFF)

getWord

public static TWord getWord(short value)
Returns a TWord initialize to the given value.

Parameters:
value - The value which the TWord should take.
Returns:
The TWord with the given value. Note that getWord(n).isInitialized() should always evaluate to true for any n.

parseWord

public static TWord parseWord(String string,
                              int radix)
                       throws NumberFormatException
Parses a TWord from a string.

Parameters:
string - The string to parse.
radix - The base of the number being parsed (probably 2, 10, or 16).
Returns:
getWord(Short.parseShort(string, radix)).
Throws:
NumberFormatException

equals

public boolean equals(Object obj)
Evaluates wheter or not two TWords have the same values. Due to the instance sharing properties of TWord, word1.equals(word2) should behave exactly like word1 == word2.

Overrides:
equals in class Object
Parameters:
obj - The object being compared to this TWord.
Returns:
True iff obj is an instance of TWord with the same initialized state and value as this TWord.

toBinaryString

public String toBinaryString(boolean distinguishUninitialized)
Returns the binary representation of this TWord. Eg. "0101101001101100"

Parameters:
distinguishUninitialized - Wheter or not to return a string of question marks if this TWord is UNINITIALIZED_VALUE.
Returns:
The binary representation of this TWord. Note that the string will be exactly 16 characters long and also that the leading zeros will be shown.

toFormattedBinaryString

public String toFormattedBinaryString(boolean distinguishUninitialized)
Returns the formatted binary representation of this TWord in which every four bits are separated by a space. Eg. "0101 1010 0110 1100"

Parameters:
distinguishUninitialized - Wheter or not to return a string of question marks if this TWord is UNINITIALIZED_VALUE.
Returns:
The formatted binary representation of this TWord. Note that the string will be exactly 19 characters long and also that the leading zeros will be shown.

toDecimalString

public String toDecimalString(boolean distinguishUninitialized)
Returns the decimal representation of this TWord. Eg. " 23148"

Parameters:
distinguishUninitialized - Wheter or not to return a string of question marks if this TWord is UNINITIALIZED_VALUE.
Returns:
The decimal representation of this TWord. This string will have exactly 6 characters; left padding will be done with spaces.

toHexString

public String toHexString(boolean distinguishUninitialized)
Returns the hexidecimal representation of this TWord. Eg. "5A6C"

Parameters:
distinguishUninitialized - Wheter or not to return a string of question marks if this TWord is UNINITIALIZED_VALUE.
Returns:
The decimal representation of this TWord. Note that the string will be exactly 4 characters long and also that the leading zeros will be shown.

toString

public String toString()
Returns the detailed representation of this TWord. Eg. "5A6C (0101 1010 0110 1100,  23148"

Overrides:
toString in class Object
Returns:
toString(false);

toString

public String toString(boolean distinguishUninitialized)
Returns the detailed representation of this TWord. Eg. "5A6C (0101 1010 0110 1100,  23148"

Parameters:
distinguishUninitialized - Wheter or not to return a string of question marks if this TWord is UNINITIALIZED_VALUE.
Returns:
The detailed representation of this TWord. Note that the string will be exactly 33 characters long and also that the leading zeros will be shown.

toPseudoCodeString

public String toPseudoCodeString(boolean distinguishUninitialized)
Returns the pseudo-code form of the TWord. Eg. "R[A] <- R[6] << R[C]"

Parameters:
distinguishUninitialized - Wheter or not to return "Uninitialized Value" if this TWord is UNINITIALIZED_VALUE.
Returns:
The pesudo-code representation of this TWord. Note that the length of the returned string is variable.

add

public static TWord add(TWord a,
                        TWord b,
                        TExceptionHandler exceptionHandler)
                 throws TException
Implements the addition operator for the TWord type. This could result in either a TException of type REGISTER_UNINITIALIZED or OVERFLOW.

Parameters:
a - The left operand.
b - The right operand.
exceptionHandler - The hander for any exceptional conditions which might be raised. If the exceptionHandler is null, all exceptions will be ignored.
Returns:
a + b.
Throws:
TException
See Also:
TExceptionType.REGISTER_UNINITIALIZED, TExceptionType.OVERFLOW

subtract

public static TWord subtract(TWord a,
                             TWord b,
                             TExceptionHandler exceptionHandler)
                      throws TException
Implements the subtraction operator for the TWord type. This could result in either a TException of type REGISTER_UNINITIALIZED or OVERFLOW.

Parameters:
a - The left operand.
b - The right operand.
exceptionHandler - The hander for any exceptional conditions which might be raised. If the exceptionHandler is null, all exceptions will be ignored.
Returns:
a - b.
Throws:
TException
See Also:
TExceptionType.REGISTER_UNINITIALIZED, TExceptionType.OVERFLOW

and

public static TWord and(TWord a,
                        TWord b,
                        TExceptionHandler exceptionHandler)
                 throws TException
Implements the bitwise-and operator for the TWord type. This could result in a TException of type REGISTER_UNINITIALIZED.

Parameters:
a - The left operand.
b - The right operand.
exceptionHandler - The hander for any exceptional conditions which might be raised. If the exceptionHandler is null, all exceptions will be ignored.
Returns:
a & b.
Throws:
TException
See Also:
TExceptionType.REGISTER_UNINITIALIZED, TExceptionType.OVERFLOW

xor

public static TWord xor(TWord a,
                        TWord b,
                        TExceptionHandler exceptionHandler)
                 throws TException
Implements the bitwise-xor operator for the TWord type. This could result in a TException of type REGISTER_UNINITIALIZED.

Parameters:
a - The left operand.
b - The right operand.
exceptionHandler - The hander for any exceptional conditions which might be raised. If the exceptionHandler is null, all exceptions will be ignored.
Returns:
a ^ b.
Throws:
TException
See Also:
TExceptionType.REGISTER_UNINITIALIZED, TExceptionType.OVERFLOW

leftShift

public static TWord leftShift(TWord a,
                              TWord b,
                              TExceptionHandler exceptionHandler)
                       throws TException
Implements the logical-left-shift operator for the TWord type. This could result in either a TException of type REGISTER_UNINITIALIZED or SHIFT_OUT_OF_BOUNDS.

Parameters:
a - The left operand.
b - The right operand.
exceptionHandler - The hander for any exceptional conditions which might be raised. If the exceptionHandler is null, all exceptions will be ignored.
Returns:
a << b.
Throws:
TException
See Also:
TExceptionType.REGISTER_UNINITIALIZED, TExceptionType.SHIFT_OUT_OF_BOUNDS

rightShift

public static TWord rightShift(TWord a,
                               TWord b,
                               TExceptionHandler exceptionHandler)
                        throws TException
Implements the arithmatic-right-shift operator for the TWord type. This could result in either a TException of type REGISTER_UNINITIALIZED or SHIFT_OUT_OF_BOUNDS.

Parameters:
a - The left operand.
b - The right operand.
exceptionHandler - The hander for any exceptional conditions which might be raised. If the exceptionHandler is null, all exceptions will be ignored.
Returns:
a >>> b.
Throws:
TException
See Also:
TExceptionType.REGISTER_UNINITIALIZED, TExceptionType.SHIFT_OUT_OF_BOUNDS

isHexDigit

public static boolean isHexDigit(char c)
Returns whether or not a character is a hexidecimal digit. This test is case-insensitive.

Parameters:
c - The character to test.
Returns:
True iff the c is a hexidecimal digit.

hexDigitToInt

public static int hexDigitToInt(char c)
Returns the hexidecimal value of a character. This function is case-insensitive.

Parameters:
c - The character to convert. If this character is not a hex digit, an IllegalArgumentException will be thrown.
Returns:
The value c interpreted as a hexidecimal digit.