mars.util
Class Binary

java.lang.Object
  extended by mars.util.Binary

public class Binary
extends Object

Some utility methods for working with binary representations.

Author:
Pete Sanderson, Ken Vollmar, and Jason Bumgarner

Constructor Summary
Binary()
           
 
Method Summary
static char binaryStringToHexDigit(String value)
          Translate String consisting of '1's and '0's into char equivalent of the corresponding hexadecimal digit.
static String binaryStringToHexString(String value)
          Translate String consisting of '1's and '0's into String equivalent of the corresponding hexadecimal value.
static int binaryStringToInt(String value)
          Translate String consisting of '1's and '0's into an int value having that binary representation.
static long binaryStringToLong(String value)
          Translate String consisting of '1's and '0's into a long value having that binary representation.
static int bitValue(int value, int bit)
          Returns the bit value of the given bit position of the given int value.
static int bitValue(long value, int bit)
          Returns the bit value of the given bit position of the given long value.
static int clearBit(int value, int bit)
          Sets the specified bit of the specified value to 0, and returns the result.
static int getByte(int value, int bite)
          Gets the specified byte of the specified value.
static String hexStringToBinaryString(String value)
          Translate String consisting of hexadecimal digits into String consisting of corresponding binary digits ('1's and '0's).
static int highOrderLongToInt(long longValue)
          Returns int representing the bit values of the high order 32 bits of given 64 bit long value.
static String intToAscii(int d)
          Produce ASCII string equivalent of integer value, interpreting it as 4 one-byte characters.
static String intToBinaryString(int value)
          Translate int value into a String consisting of '1's and '0's.
static String intToBinaryString(int value, int length)
          Translate int value into a String consisting of '1's and '0's.
static String intToHalfHexString(int d)
          Returns a 6 character string representing the 16-bit hexadecimal equivalent of the given integer value.
static String intToHexString(int d)
          Prefix a hexadecimal-indicating string "0x" to the string which is returned by the method "Integer.toHexString".
static boolean isHex(String v)
          Parsing method to see if a string represents a hex number.
static boolean isOctal(String v)
          Parsing method to see if a string represents an octal number.
static String longToBinaryString(long value)
          Translate long value into a String consisting of '1's and '0's.
static String longToBinaryString(long value, int length)
          Translate long value into a String consisting of '1's and '0's.
static String longToHexString(long value)
          Prefix a hexadecimal-indicating string "0x" to the string equivalent to the hexadecimal value in the long parameter.
static int lowOrderLongToInt(long longValue)
          Returns int representing the bit values of the low order 32 bits of given 64 bit long value.
static int setBit(int value, int bit)
          Sets the specified bit of the specified value to 1, and returns the result.
static int setByte(int value, int bite, int replace)
          Sets the specified byte of the specified value to the low order 8 bits of specified replacement value, and returns the result.
static int stringToInt(String s)
          Attempt to validate given string whose characters represent a 32 bit integer.
static long stringToLong(String s)
          Attempt to validate given string whose characters represent a 64 bit long.
static long twoIntsToLong(int highOrder, int lowOrder)
          Returns long (64 bit integer) combining the bit values of two given 32 bit integer values.
static String unsignedIntToIntString(int d)
          Produce String equivalent of integer value interpreting it as an unsigned integer.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Binary

public Binary()
Method Detail

intToBinaryString

public static String intToBinaryString(int value,
                                       int length)
Translate int value into a String consisting of '1's and '0's.

Parameters:
value - The int value to convert.
length - The number of bit positions, starting at least significant, to process.
Returns:
String consisting of '1' and '0' characters corresponding to the requested binary sequence.

intToBinaryString

public static String intToBinaryString(int value)
Translate int value into a String consisting of '1's and '0's. Assumes all 32 bits are to be translated.

Parameters:
value - The int value to convert.
Returns:
String consisting of '1' and '0' characters corresponding to the requested binary sequence.

longToBinaryString

public static String longToBinaryString(long value,
                                        int length)
Translate long value into a String consisting of '1's and '0's.

Parameters:
value - The long value to convert.
length - The number of bit positions, starting at least significant, to process.
Returns:
String consisting of '1' and '0' characters corresponding to the requested binary sequence.

longToBinaryString

public static String longToBinaryString(long value)
Translate long value into a String consisting of '1's and '0's. Assumes all 64 bits are to be translated.

Parameters:
value - The long value to convert.
Returns:
String consisting of '1' and '0' characters corresponding to the requested binary sequence.

binaryStringToInt

public static int binaryStringToInt(String value)
Translate String consisting of '1's and '0's into an int value having that binary representation. The String is assumed to be at most 32 characters long. No error checking is performed. String position 0 has most-significant bit, position length-1 has least-significant.

Parameters:
value - The String value to convert.
Returns:
int whose binary value corresponds to decoded String.

binaryStringToLong

public static long binaryStringToLong(String value)
Translate String consisting of '1's and '0's into a long value having that binary representation. The String is assumed to be at most 64 characters long. No error checking is performed. String position 0 has most-significant bit, position length-1 has least-significant.

Parameters:
value - The String value to convert.
Returns:
long whose binary value corresponds to decoded String.

binaryStringToHexString

public static String binaryStringToHexString(String value)
Translate String consisting of '1's and '0's into String equivalent of the corresponding hexadecimal value. No length limit. String position 0 has most-significant bit, position length-1 has least-significant.

Parameters:
value - The String value to convert.
Returns:
String containing '0', '1', ...'F' characters which form hexadecimal equivalent of decoded String.

hexStringToBinaryString

public static String hexStringToBinaryString(String value)
Translate String consisting of hexadecimal digits into String consisting of corresponding binary digits ('1's and '0's). No length limit. String position 0 will have most-significant bit, position length-1 has least-significant.

Parameters:
value - String containing '0', '1', ...'f' characters which form hexadecimal. Letters may be either upper or lower case. Works either with or without leading "Ox".
Returns:
String with equivalent value in binary.

binaryStringToHexDigit

public static char binaryStringToHexDigit(String value)
Translate String consisting of '1's and '0's into char equivalent of the corresponding hexadecimal digit. String limited to length 4. String position 0 has most-significant bit, position length-1 has least-significant.

Parameters:
value - The String value to convert.
Returns:
char '0', '1', ...'F' which form hexadecimal equivalent of decoded String. If string length > 4, returns '0'.

intToHexString

public static String intToHexString(int d)
Prefix a hexadecimal-indicating string "0x" to the string which is returned by the method "Integer.toHexString". Prepend leading zeroes to that string as necessary to make it always eight hexadecimal digits.

Parameters:
d - The int value to convert.
Returns:
String containing '0', '1', ...'F' which form hexadecimal equivalent of int.

intToHalfHexString

public static String intToHalfHexString(int d)
Returns a 6 character string representing the 16-bit hexadecimal equivalent of the given integer value. First two characters are "0x". It assumes value will "fit" in 16 bits. If non-negative, prepend leading zeroes to that string as necessary to make it always four hexadecimal digits. If negative, chop off the first four 'f' digits so result is always four hexadecimal digits

Parameters:
d - The int value to convert.
Returns:
String containing '0', '1', ...'F' which form hexadecimal equivalent of int.

longToHexString

public static String longToHexString(long value)
Prefix a hexadecimal-indicating string "0x" to the string equivalent to the hexadecimal value in the long parameter. Prepend leading zeroes to that string as necessary to make it always sixteen hexadecimal digits.

Parameters:
value - The long value to convert.
Returns:
String containing '0', '1', ...'F' which form hexadecimal equivalent of long.

unsignedIntToIntString

public static String unsignedIntToIntString(int d)
Produce String equivalent of integer value interpreting it as an unsigned integer. For instance, -1 (0xffffffff) produces "4294967295" instead of "-1".

Parameters:
d - The int value to interpret.
Returns:
String which forms unsigned 32 bit equivalent of int.

intToAscii

public static String intToAscii(int d)
Produce ASCII string equivalent of integer value, interpreting it as 4 one-byte characters. If the value in a given byte does not correspond to a printable character, it will be assigned a default character (defined in config.properties) for a placeholder.

Parameters:
d - The int value to interpret
Returns:
String that represents ASCII equivalent

stringToInt

public static int stringToInt(String s)
                       throws NumberFormatException
Attempt to validate given string whose characters represent a 32 bit integer. Integer.decode() is insufficient because it will not allow incorporation of hex two's complement (i.e. 0x80...0 through 0xff...f). Allows optional negative (-) sign but no embedded spaces.

Parameters:
s - candidate string
Returns:
returns int value represented by given string
Throws:
NumberFormatException - if string cannot be translated into an int

stringToLong

public static long stringToLong(String s)
                         throws NumberFormatException
Attempt to validate given string whose characters represent a 64 bit long. Long.decode() is insufficient because it will not allow incorporation of hex two's complement (i.e. 0x80...0 through 0xff...f). Allows optional negative (-) sign but no embedded spaces.

Parameters:
s - candidate string
Returns:
returns long value represented by given string
Throws:
NumberFormatException - if string cannot be translated into a long

highOrderLongToInt

public static int highOrderLongToInt(long longValue)
Returns int representing the bit values of the high order 32 bits of given 64 bit long value.

Parameters:
longValue - The long value from which to extract bits.
Returns:
int containing high order 32 bits of argument

lowOrderLongToInt

public static int lowOrderLongToInt(long longValue)
Returns int representing the bit values of the low order 32 bits of given 64 bit long value.

Parameters:
longValue - The long value from which to extract bits.
Returns:
int containing low order 32 bits of argument

twoIntsToLong

public static long twoIntsToLong(int highOrder,
                                 int lowOrder)
Returns long (64 bit integer) combining the bit values of two given 32 bit integer values.

Parameters:
highOrder - Integer to form the high-order 32 bits of result.
lowOrder - Integer to form the high-order 32 bits of result.
Returns:
long containing concatenated 32 bit int values.

bitValue

public static int bitValue(int value,
                           int bit)
Returns the bit value of the given bit position of the given int value.

Parameters:
value - The value to read the bit from.
bit - bit position in range 0 (least significant) to 31 (most)
Returns:
0 if the bit position contains 0, and 1 otherwise.

bitValue

public static int bitValue(long value,
                           int bit)
Returns the bit value of the given bit position of the given long value.

Parameters:
value - The value to read the bit from.
bit - bit position in range 0 (least significant) to 63 (most)
Returns:
0 if the bit position contains 0, and 1 otherwise.

setBit

public static int setBit(int value,
                         int bit)
Sets the specified bit of the specified value to 1, and returns the result.

Parameters:
value - The value in which the bit is to be set.
bit - bit position in range 0 (least significant) to 31 (most)
Returns:
value possibly modified with given bit set to 1.

clearBit

public static int clearBit(int value,
                           int bit)
Sets the specified bit of the specified value to 0, and returns the result.

Parameters:
value - The value in which the bit is to be set.
bit - bit position in range 0 (least significant) to 31 (most)
Returns:
value possibly modified with given bit set to 0.

setByte

public static int setByte(int value,
                          int bite,
                          int replace)
Sets the specified byte of the specified value to the low order 8 bits of specified replacement value, and returns the result.

Parameters:
value - The value in which the byte is to be set.
bite - byte position in range 0 (least significant) to 3 (most)
replace - value to place into that byte position - use low order 8 bits
Returns:
value modified value.

getByte

public static int getByte(int value,
                          int bite)
Gets the specified byte of the specified value.

Parameters:
value - The value in which the byte is to be retrieved.
bite - byte position in range 0 (least significant) to 3 (most)
Returns:
zero-extended byte value in low order byte.

isHex

public static boolean isHex(String v)
Parsing method to see if a string represents a hex number. As per http://java.sun.com/j2se/1.4.2/docs/api/java/lang/Integer.html#decode(java.lang.String), a string represents a hex number if the string is in the forms: Signopt 0x HexDigits Signopt 0X HexDigits Signopt # HexDigits <---- Disallow this form since # is MIPS comment

Parameters:
v - String containing numeric digits (could be decimal, octal, or hex)
Returns:
Returns true if string represents a hex number, else returns false.

isOctal

public static boolean isOctal(String v)
Parsing method to see if a string represents an octal number. As per http://java.sun.com/j2se/1.4.2/docs/api/java/lang/Integer.html#decode(java.lang.String), a string represents an octal number if the string is in the forms: Signopt 0 OctalDigits

Parameters:
v - String containing numeric digits (could be decimal, octal, or hex)
Returns:
Returns true if string represents an octal number, else returns false.