## mars.util
Class Binary

    java.lang.Object
      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`.