Package ghidra.util

# Class NumericUtilities

java.lang.Object
ghidra.util.NumericUtilities

public final class NumericUtilities extends Object

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final BigInteger`
  `MAX_SIGNED_LONG`
  `static final BigInteger`
  `MAX_UNSIGNED_INT`
  `static final long`
  `MAX_UNSIGNED_INT32_AS_LONG`
  `static final BigInteger`
  `MAX_UNSIGNED_LONG`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static long`
  `bigIntegerToUnsignedLong(BigInteger value)`
  `static String`
  `convertBytesToString(byte[] bytes)`
  Convert a byte array into a hexadecimal string.
  `static String`
  `convertBytesToString(byte[] bytes, int start, int len, String delimeter)`
  Convert a byte array into a hexadecimal string.
  `static String`
  `convertBytesToString(byte[] bytes, String delimeter)`
  Convert a byte array into a hexadecimal string.
  `static String`
  `convertBytesToString(Iterable<Byte> bytes, String delimiter)`
  Convert a bytes into a hexadecimal string.
  `static String`
  `convertBytesToString(Iterator<Byte> bytes, String delimiter)`
  Convert a bytes into a hexadecimal string.
  `static String`
  `convertBytesToString(Stream<Byte> bytes, String delimiter)`
  Convert a bytes into a hexadecimal string.
  `static void`
  `convertHexStringToMaskedValue(AtomicLong msk, AtomicLong val, String hex, int n, int spaceevery, String spacer)`
  The reverse of `convertMaskedValueToHexString(long, long, int, boolean, int, String)`
  `static String`
  `convertMaskedValueToHexString(long msk, long val, int n, boolean truncate, int spaceevery, String spacer)`
  Convert a masked value into a hexadecimal-ish string.
  `static String`
  `convertMaskToHexString(long msk, int n, boolean truncate, int spaceevery, String spacer)`
  Convert a mask to a hexadecimal-ish string.
  `static byte[]`
  `convertStringToBytes(String hexString)`
  Parse hexadecimal digits into a byte array.
  `static BigInteger`
  `decodeBigInteger(String s)`
  Decode a big integer in hex, binary, octal, or decimal, based on the prefix 0x, 0b, or 0.
  `static String`
  `formatNumber(long number, int radix)`
  Render `number` in different bases using the default signedness mode.
  `static String`
  `formatNumber(long number, int radix, SignednessFormatMode mode)`
  Provide renderings of `number` in different bases: `0` - renders `number` as an escaped character sequence `2` - renders `number` as a `base-2` integer `8` - renders `number` as a `base-8` integer `10` - renders `number` as a `base-10` integer `16` (default) - renders `number` as a `base-16` integer Number Radix DEFAULT Mode Alias UNSIGNED Mode Value SIGNED Mode Value 100 2 UNSIGNED 1100100b 1100100b 100 8 UNSIGNED 144o 144o 100 10 SIGNED 100 100 100 16 UNSIGNED 64h 64h -1 2 UNSIGNED 1111111111111111111111111111111111111111111111111111111111111111b -1b -1 8 UNSIGNED 1777777777777777777777o -1o -1 10 SIGNED 18446744073709551615 -1 -1 16 UNSIGNED ffffffffffffffffh -1h -100 2 UNSIGNED 1111111111111111111111111111111111111111111111111111111110011100b -1100100b -100 8 UNSIGNED 1777777777777777777634o -144o -100 10 SIGNED 18446744073709551516 -100 -100 16 UNSIGNED ffffffffffffff9ch -64h
  `static long`
  `getUnsignedAlignedValue(long unsignedValue, long alignment)`
  Get an unsigned aligned value corresponding to the specified unsigned value which will be greater than or equal the specified value.
  `static boolean`
  `isFloatingPointType(Class<?> numClass)`
  Determine if the provided Number class is a floating-point type.
  `static boolean`
  `isFloatingPointType(Number number)`
  Determine if the provided Number is a floating-point type -- Float or Double.
  `static boolean`
  `isIntegerType(Class<?> numClass)`
  Determine if the provided Number class is an integer type.
  `static boolean`
  `isIntegerType(Number number)`
  Determine if the provided Number is an integer type -- Byte, Short, Integer, or Long.
  `static BigInteger`
  `parseHexBigInteger(String s)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  use `parseHexLong(String)` instead
  `static long`
  `parseHexLong(String s)`
  Parses the given hex string as a `long` value.
  `static int`
  `parseInt(String s)`
  Parses the given decimal/hex string as an `int` value.
  `static int`
  `parseInt(String s, int defaultValue)`
  Parses the given decimal/hex string as an `int` value.
  `static long`
  `parseLong(String s)`
  Parses the given decimal/hex string as an `long` value.
  `static long`
  `parseLong(String s, long defaultValue)`
  Parses the given decimal/hex string as an `long` value.
  `static long`
  `parseNumber(String numStr)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  use `parseLong(String)` instead
  `static Long`
  `parseNumber(String s, Long defaultValue)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  use `parseLong(String, long)` instead
  `static final String`
  `toHexString(long value)`
  returns the value of the specified long as hexadecimal, prefixing with the `HEX_PREFIX_x` string.
  `static final String`
  `toHexString(long value, int size)`
  returns the value of the specified long as hexadecimal, prefixing with the `HEX_PREFIX_x` string.
  `static final String`
  `toSignedHexString(long value)`
  returns the value of the specified long as signed hexadecimal, prefixing with the `HEX_PREFIX_x` string.
  `static String`
  `toString(byte b)`
  Convert the given byte into a two character String, padding with a leading 0 if needed.
  `static BigInteger`
  `unsignedLongToBigInteger(long value)`
  Converts a unsigned long value, which is currently stored in a java signed long, into a `BigInteger`.
  `static double`
  `unsignedLongToDouble(long val)`
  Convert a long, treated as unsigned, to a double

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### MAX_UNSIGNED_LONG

    public static final BigInteger MAX_UNSIGNED_LONG

  - ### MAX_SIGNED_LONG

    public static final BigInteger MAX_SIGNED_LONG

  - ### MAX_UNSIGNED_INT

    public static final BigInteger MAX_UNSIGNED_INT

  - ### MAX_UNSIGNED_INT32_AS_LONG

    public static final long MAX_UNSIGNED_INT32_AS_LONG
    See Also:
      - Constant Field Values

- ## Method Details

  - ### parseNumber

    @Deprecated(since="11.3", forRemoval=true) public static long parseNumber(String numStr)
    Deprecated, for removal: This API element is subject to removal in a future version.
    use `parseLong(String)` instead
    Parses the given string as a numeric value, detecting whether or not it begins with a hex prefix, and if not, parses as a long int value.
    Parameters:
      `numStr` - the number string
    Returns:
      the long value or 0

  - ### parseNumber

    @Deprecated(since="11.3", forRemoval=true) public static Long parseNumber(String s, Long defaultValue)
    Deprecated, for removal: This API element is subject to removal in a future version.
    use `parseLong(String, long)` instead
    Parses the given string as a numeric value, detecting whether or not it begins with a hex prefix, and if not, parses as a long int value.
    Parameters:
      `s` - the string to parse
      `defaultValue` - the default value to use if the string cannot be parsed
    Returns:
      the long value

  - ### parseInt

    public static int parseInt(String s) throws NumberFormatException
    Parses the given decimal/hex string as an `int` value. This method allows values with the top bit set to be implicitly parsed as negative values.
    Parameters:
      `s` - the string to parse
    Returns:
      the parsed `int` value
    Throws:
      `NumberFormatException` - if the string does not represent a valid `int` value

  - ### parseInt

    public static int parseInt(String s, int defaultValue)
    Parses the given decimal/hex string as an `int` value. This method allows values with the top bit set to be implicitly parsed as negative values.
    Parameters:
      `s` - the string to parse
      `defaultValue` - the default value to return if the string does not represent a valid `int` value
    Returns:
      the parsed `int` value or the `defaultValue` if the string does not represent a valid `int` value

  - ### parseLong

    public static long parseLong(String s) throws NumberFormatException
    Parses the given decimal/hex string as an `long` value. This method allows values with the top bit set to be implicitly parsed as negative values.
    Parameters:
      `s` - the string to parse
    Returns:
      the parsed `long` value
    Throws:
      `NumberFormatException` - if the string does not represent a valid `long` value

  - ### parseLong

    public static long parseLong(String s, long defaultValue)
    Parses the given decimal/hex string as an `long` value. This method allows values with the top bit set to be implicitly parsed as negative values.
    Parameters:
      `s` - the string to parse
      `defaultValue` - the default value to return if the string does not represent a valid `long` value
    Returns:
      the parsed `long` value or the `defaultValue` if the string does not represent a valid `long` value

  - ### parseHexLong

    public static long parseHexLong(String s) throws NumberFormatException
    Parses the given hex string as a `long` value.

    Note: The string is treated as hex regardless of whether or not it contains the `0x` prefix.

    Parameters:
      `s` - the string to parse
    Returns:
      the parsed `long` value
    Throws:
      `NumberFormatException` - if the string does not represent a valid value

  - ### parseHexBigInteger

    @Deprecated(since="11.3", forRemoval=true) public static BigInteger parseHexBigInteger(String s) throws NumberFormatException
    Deprecated, for removal: This API element is subject to removal in a future version.
    use `parseHexLong(String)` instead
    Parses the given hex string as a `BigInteger` value.

    Note: The string is treated as hex regardless of whether or not it contains the `0x` prefix.

    Parameters:
      `s` - the string to parse
    Returns:
      the parsed `BigInteger` value
    Throws:
      `NumberFormatException` - if the string does not represent a valid value

  - ### decodeBigInteger

    public static BigInteger decodeBigInteger(String s)
    Decode a big integer in hex, binary, octal, or decimal, based on the prefix 0x, 0b, or 0.

    This checks for the presence of a case-insensitive prefix. 0x denotes hex, 0b denotes binary, 0 denotes octal. If no prefix is given, decimal is assumed. A sign +/- may immediately precede the prefix. If no sign is given, a positive value is assumed.

    Parameters:
      `s` - the string to parse
    Returns:
      the decoded value

  - ### toHexString

    public static final String toHexString(long value)
    returns the value of the specified long as hexadecimal, prefixing with the `HEX_PREFIX_x` string.
    Parameters:
      `value` - the long value to convert
    Returns:
      the string

  - ### toHexString

    public static final String toHexString(long value, int size)
    returns the value of the specified long as hexadecimal, prefixing with the `HEX_PREFIX_x` string.
    Parameters:
      `value` - the long value to convert
      `size` - number of bytes to be represented
    Returns:
      the string

  - ### toSignedHexString

    public static final String toSignedHexString(long value)
    returns the value of the specified long as signed hexadecimal, prefixing with the `HEX_PREFIX_x` string.
    Parameters:
      `value` - the long value to convert
    Returns:
      the string

  - ### unsignedLongToBigInteger

    public static BigInteger unsignedLongToBigInteger(long value)
    Converts a unsigned long value, which is currently stored in a java signed long, into a `BigInteger`.

    In other words, the full 64 bits of the primitive java signed long is being used to store an unsigned value. This method converts this into a positive BigInteger value.

    Parameters:
      `value` - java unsigned long value stuffed into a java signed long
    Returns:
      new `BigInteger` with the positive value of the unsigned long value

  - ### bigIntegerToUnsignedLong

    public static long bigIntegerToUnsignedLong(BigInteger value)

  - ### unsignedLongToDouble

    public static double unsignedLongToDouble(long val)
    Convert a long, treated as unsigned, to a double
    Parameters:
      `val` - the long to treat as unsigned and convert
    Returns:
      the double

  - ### getUnsignedAlignedValue

    public static long getUnsignedAlignedValue(long unsignedValue, long alignment)
    Get an unsigned aligned value corresponding to the specified unsigned value which will be greater than or equal the specified value.
    Parameters:
      `unsignedValue` - value to be aligned
      `alignment` - alignment
    Returns:
      aligned value

  - ### convertMaskedValueToHexString

    public static String convertMaskedValueToHexString(long msk, long val, int n, boolean truncate, int spaceevery, String spacer)
    Convert a masked value into a hexadecimal-ish string. Converts the data to hexadecimal, placing an X where a nibble is unknown. Where a nibble is partially defined, it is displayed as four bits in brackets []. Bits are displayed as x, or the defined value. For example, consider the mask 00001111:01011100, and the value 00001001:00011000. This will display as `X8:[x0x1][10xx]`. To see the correlation, consider the table:

    Display | `X` | `8` | `:` | `[x0x1]` | `[10xx]`
    --- | --- | --- | --- | --- | ---
    Mask | `0000` | `1111` | `:` | `0101` | `1100`
    Value | `0000` | `1000` | `:` | `0001` | `1000`

    Parameters:
      `msk` - the mask
      `val` - the value
      `n` - the number of nibbles, starting at the right. The example uses 4.
      `truncate` - true if leading Xs may be truncated. The example uses `false`.
      `spaceevery` - how many nibbles in spaced groups, 0 for no spaces. The example uses 2.
      `spacer` - the group separator, if applicable. The example uses `':'`.
    Returns:
      the string representation
    See Also:
      - `convertMaskToHexString(long, int, boolean, int, String)`
      - `convertHexStringToMaskedValue(AtomicLong, AtomicLong, String, int, int, String)`

  - ### convertMaskToHexString

    public static String convertMaskToHexString(long msk, int n, boolean truncate, int spaceevery, String spacer)
    Convert a mask to a hexadecimal-ish string. Converts the mask in a similar way to `convertMaskedValueToHexString(long, long, int, boolean, int, String)`. Philosophically, it is hexadecimal, but the only valid digits are 0 and F. Any partially-included nibble will be broken down into bracketed bits. Displaying masks in this way is convenient when shown proximal to related masked values.
    Parameters:
      `msk` - the mask
      `n` - the number of nibbles, starting at the right
      `truncate` - true if leading Xs may be truncated
      `spaceevery` - how many nibbles in spaced groups, 0 for no spaces
      `spacer` - the group separator, if applicable
    Returns:
      the string representation
    See Also:
      - `convertMaskedValueToHexString(long, long, int, boolean, int, String)`
      - `convertHexStringToMaskedValue(AtomicLong, AtomicLong, String, int, int, String)`

  - ### convertHexStringToMaskedValue

    public static void convertHexStringToMaskedValue(AtomicLong msk, AtomicLong val, String hex, int n, int spaceevery, String spacer)
    The reverse of `convertMaskedValueToHexString(long, long, int, boolean, int, String)`
    Parameters:
      `msk` - an object to receive the resulting mask
      `val` - an object to receive the resulting value
      `hex` - the input string to parse
      `n` - the number of nibbles to parse (they are stored right aligned in the result)
      `spaceevery` - how many nibbles are expected between spacers
      `spacer` - the spacer
    See Also:
      - `convertMaskedValueToHexString(long, long, int, boolean, int, String)`
      - `convertMaskToHexString(long, int, boolean, int, String)`

  - ### formatNumber

    public static String formatNumber(long number, int radix)
    Render `number` in different bases using the default signedness mode.

    This invokes formatNumber(long, int, SignednessFormatMode) with a `mode` parameter of `SignednessFormatMode.DEFAULT`.

    Parameters:
      `number` - The number to represent
      `radix` - the base in which `number` is represented
    Returns:
      formatted string of the number parameter in provided radix base
    See Also:
      - `formatNumber(long, int, SignednessFormatMode)`

  - ### formatNumber

    public static String formatNumber(long number, int radix, SignednessFormatMode mode)
    Provide renderings of `number` in different bases:
    - `0` - renders `number` as an escaped character sequence
    - `2` - renders `number` as a `base-2` integer
    - `8` - renders `number` as a `base-8` integer
    - `10` - renders `number` as a `base-10` integer
    - `16` (default) - renders `number` as a `base-16` integer

    Number | Radix | DEFAULT Mode Alias | UNSIGNED Mode Value | SIGNED Mode Value
    --- | --- | --- | --- | ---
    100 | 2 | UNSIGNED | 1100100b | 1100100b
    100 | 8 | UNSIGNED | 144o | 144o
    100 | 10 | SIGNED | 100 | 100
    100 | 16 | UNSIGNED | 64h | 64h
    -1 | 2 | UNSIGNED | 1111111111111111111111111111111111111111111111111111111111111111b | -1b
    -1 | 8 | UNSIGNED | 1777777777777777777777o | -1o
    -1 | 10 | SIGNED | 18446744073709551615 | -1
    -1 | 16 | UNSIGNED | ffffffffffffffffh | -1h
    -100 | 2 | UNSIGNED | 1111111111111111111111111111111111111111111111111111111110011100b | -1100100b
    -100 | 8 | UNSIGNED | 1777777777777777777634o | -144o
    -100 | 10 | SIGNED | 18446744073709551516 | -100
    -100 | 16 | UNSIGNED | ffffffffffffff9ch | -64h

    Parameters:
      `number` - The number to represent
      `radix` - The base in which `number` is represented
      `mode` - Specifies how the number is formatted with respect to its signed-ness
    Returns:
      number string in the given base

  - ### convertStringToBytes

    public static byte[] convertStringToBytes(String hexString)
    Parse hexadecimal digits into a byte array.
    Parameters:
      `hexString` - hexadecimal digits
    Returns:
      numeric value as a byte array, or null if string contains invalid hex characters.

  - ### toString

    public static String toString(byte b)
    Convert the given byte into a two character String, padding with a leading 0 if needed.
    Parameters:
      `b` - the byte
    Returns:
      the byte string

  - ### convertBytesToString

    public static String convertBytesToString(byte[] bytes)
    Convert a byte array into a hexadecimal string.
    Parameters:
      `bytes` - byte array
    Returns:
      hex string representation

  - ### convertBytesToString

    public static String convertBytesToString(byte[] bytes, String delimeter)
    Convert a byte array into a hexadecimal string.
    Parameters:
      `bytes` - byte array
      `delimeter` - the text between byte strings
    Returns:
      hex string representation

  - ### convertBytesToString

    public static String convertBytesToString(byte[] bytes, int start, int len, String delimeter)
    Convert a byte array into a hexadecimal string.
    Parameters:
      `bytes` - byte array
      `start` - start index
      `len` - number of bytes to convert
      `delimeter` - the text between byte strings
    Returns:
      hex string representation

  - ### convertBytesToString

    public static String convertBytesToString(Iterator<Byte> bytes, String delimiter)
    Convert a bytes into a hexadecimal string.
    Parameters:
      `bytes` - an iterator of bytes
      `delimiter` - the text between byte strings; null is allowed
    Returns:
      hex string representation

  - ### convertBytesToString

    public static String convertBytesToString(Iterable<Byte> bytes, String delimiter)
    Convert a bytes into a hexadecimal string.
    Parameters:
      `bytes` - an iterable of bytes
      `delimiter` - the text between byte strings; null is allowed
    Returns:
      hex string representation

  - ### convertBytesToString

    public static String convertBytesToString(Stream<Byte> bytes, String delimiter)
    Convert a bytes into a hexadecimal string.
    Parameters:
      `bytes` - an stream of bytes
      `delimiter` - the text between byte strings; null is allowed
    Returns:
      hex string representation

  - ### isIntegerType

    public static boolean isIntegerType(Number number)
    Determine if the provided Number is an integer type -- Byte, Short, Integer, or Long.
    Parameters:
      `number` - the object to check for for integer-type
    Returns:
      true if the provided number is an integer-type, false otherwise

  - ### isIntegerType

    public static boolean isIntegerType(Class<?> numClass)
    Determine if the provided Number class is an integer type.
    Parameters:
      `numClass` - Class of an object
    Returns:
      true if the class parameter is a integer type, false otherwise

  - ### isFloatingPointType

    public static boolean isFloatingPointType(Number number)
    Determine if the provided Number is a floating-point type -- Float or Double.
    Parameters:
      `number` - the object to check for for floating-point-type
    Returns:
      true if the provided number is a floating-point-type, false otherwise

  - ### isFloatingPointType

    public static boolean isFloatingPointType(Class<?> numClass)
    Determine if the provided Number class is a floating-point type.
    Parameters:
      `numClass` - Class of an object
    Returns:
      true if the class parameter is a floating-point type, false otherwise