edu.princeton.toy.lang

Class TWord

java.lang.Object

edu.princeton.toy.lang.TWord

public class TWord
extends java.lang.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:

• The isInitialized() method returns false in UNINITIALIZED_VALUE but not in getWord(0).
• The to_____String() methods will return question marks if the distinguishUninitialized argument is true.
• Performing arithmatic operations on uninitialized values will cause an exception of the family TExceptionType.UNINITIALIZED_FAMILY to be raised.

Field Summary

Fields

Modifier and Type	Field and Description
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 java.lang.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

Methods

Modifier and Type	Method and Description
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.
static java.lang.String	commentLine(java.lang.String line) takes a line that has an instruction and inserts a comment into the line preserving what ever user comments there are.
boolean	equals(java.lang.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	isCommand(java.lang.String cmd) checks if the given parameter is a valid TOY instruction
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 boolean	isPseudoCode(java.lang.String str) Checks if the given string is a valid TOY pseudocode
static TWord	leftShift(TWord a, TWord b, TExceptionHandler exceptionHandler) Implements the logical-left-shift operator for the TWord type.
static TWord	parseWord(java.lang.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.
java.lang.String	toBinaryString(boolean distinguishUninitialized) Returns the binary representation of this TWord.
java.lang.String	toDecimalString(boolean distinguishUninitialized) Returns the decimal representation of this TWord.
java.lang.String	toFormattedBinaryString(boolean distinguishUninitialized) Returns the formatted binary representation of this TWord in which every four bits are separated by a space.
java.lang.String	toHexString(boolean distinguishUninitialized) Returns the hexidecimal representation of this TWord.
java.lang.String	toPseudoCodeString(boolean distinguishUninitialized) Returns the pseudo-code form of the TWord.
java.lang.String	toString() Returns the detailed representation of this TWord.
java.lang.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 java.lang.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:

• The isInitialized() method returns false in UNINITIALIZED_VALUE but not in getWord(0).
• The to_____String() methods will return question marks if the distinguishUninitialized argument is true.
• Performing arithmatic operations on uninitialized values will cause an exception of the family TExceptionType.UNINITIALIZED_FAMILY to be raised.

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

isCommand

public static boolean isCommand(java.lang.String cmd)

checks if the given parameter is a valid TOY instruction

commentLine

public static java.lang.String commentLine(java.lang.String line)

takes a line that has an instruction and inserts a comment into the line preserving what ever user comments there are. If what follows the instruction is a pseudocode string, this pseudocode is replaced with the new one.

isPseudoCode

public static boolean isPseudoCode(java.lang.String str)

Checks if the given string is a valid TOY pseudocode

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(java.lang.String string,
              int radix)
                       throws java.lang.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:

java.lang.NumberFormatException

equals

public boolean equals(java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.String toString()

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

Overrides:

toString in class java.lang.Object

Returns:

toString(false);

toString

public java.lang.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 java.lang.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.