Package net.solarnetwork.util

Class NumberUtils

java.lang.Object
net.solarnetwork.util.NumberUtils
public final class NumberUtils extends Object
Utilities for dealing with numbers.
Since:
1.42
Version:
1.10
Author:
matt

  • Method Details

    • unsigned

      public static short unsigned(byte data)
      Convert a signed byte into an unsigned short value.

      The returned short will have a value between 0 and 255.

      Parameters:
      data - the byte
      Returns:
      the unsigned value

    • unsigned

      public static short[] unsigned(byte[] data)
      Convert signed bytes into unsigned short values.

      The returned shorts will have values between 0 and 255.

      Parameters:
      data - the bytes
      Returns:
      the unsigned values, or null if data is null

    • unsignedNumber

      public static Number unsignedNumber(Number value)
      Convert a signed whole number into an unsigned equivalent.

      This method attempts to return the next-largest data type for the unsigned conversion, e.g. an unsigned int will be returned for a signed short.

      Parameters:
      value - the signed whole number to convert
      Returns:
      the unsigned value, or null if value is null

    • bigDecimalForNumber

      public static BigDecimal bigDecimalForNumber(Number value)
      Get a BigDecimal for a number.

      If value is already a BigDecimal it will be returned directly. Otherwise a new BigDecimal instance will be created out of value.

      Parameters:
      value - the number to get a BigDecimal version of
      Returns:
      the BigDecimal version of value, or null if value is null

    • bigIntegerForNumber

      public static BigInteger bigIntegerForNumber(Number value)
      Get a BigInteger for a number.

      If value is already a BigInteger it will be returned directly. Otherwise a new BigInteger instance will be created out of value.

      Parameters:
      value - the number to get a BigInteger version of
      Returns:
      the BigInteger version of value, or null if value is null
      Since:
      1.8

    • decimalArray

      public static BigDecimal[] decimalArray(String... nums)
      Get an array of BigDecimal instances from string values.
      Parameters:
      nums - the string numbers
      Returns:
      the array
      Throws:
      NumberFormatException - if any number is not a valid representation of a BigDecimal
      Since:
      1.6

    • crc16

      public static int crc16(byte[] data, int offset, int length)
      Calculate the CRC-16 checksum value from a set of data.

      Adapted from https://introcs.cs.princeton.edu/java/61data/CRC16.java.

      Parameters:
      data - the data to checksum
      offset - the offset within the data to start
      length - the length of data to checksum
      Returns:
      the checksum value
      Since:
      1.1

    • wholePartToInteger

      public static BigInteger wholePartToInteger(BigDecimal decimal)
      Get the whole part of a BigDecimal as a BigInteger.

      If whole portion of the decimal is returned without any rounding from the fractional part of the decimal.

      Parameters:
      decimal - the decimal
      Returns:
      the whole part as an integer, or zero if decimal is null
      Since:
      1.2

    • fractionalPartToInteger

      public static BigInteger fractionalPartToInteger(BigDecimal decimal)
      Get the fractional part of a BigDecimal as a BigInteger.
      Parameters:
      decimal - the decimal
      Returns:
      the fractional part as an integer, or zero if decimal is null
      Since:
      1.2

    • fractionalPartToInteger

      public static BigInteger fractionalPartToInteger(BigDecimal decimal, int maxScale)
      Get the fractional part of a BigDecimal as a BigInteger with a maximum scale.

      If the fractional part must be rounded, the RoundingMode.FLOOR method (when positive) or RoundingMode.CEILING (when negative) will be used to truncate the value to keep it within the desired scale.

      Parameters:
      decimal - the decimal
      maxScale - the maximum power-of-10 scale
      Returns:
      the fractional part as an integer, or zero if decimal is null
      Since:
      1.2

    • fractionalPartScaledToInteger

      public static BigInteger fractionalPartScaledToInteger(BigDecimal decimal, int scale)
      Get the fractional part of a BigDecimal as a BigInteger, scaled by some power of ten.

      For example, to convert the fractional part to "nano" scale, pass in 9 for the scale.

      Parameters:
      decimal - the decimal to get the scaled fractional part from
      scale - the power of 10 to scale by; a negative value shifts the decimal point left this many places; a positive value shifts the decimal point right this many places
      Returns:
      the fractional part as an integer, or zero if decimal is null
      Since:
      1.2

    • scaled

      public static BigDecimal scaled(Number num, int scale)
      Scale a number by a power of 10.
      Parameters:
      num - the number to scale
      scale - the power of 10 to scale by; a negative value shifts the decimal point left this many places; a positive value shifts the decimal point right this many places
      Returns:
      the scaled value
      Since:
      1.2

    • maximumDecimalScale

      public static Number maximumDecimalScale(Number value, int maxDecimalScale)
      Apply a maximum decimal scale to a number value.
      Parameters:
      value - the number to apply the maximum scale to
      maxDecimalScale - the maximum scale, or -1 for no maximum
      Returns:
      the value, possibly rounded to decimalScale
      Since:
      1.3

    • multiplied

      public static Number multiplied(Number value, BigDecimal multiple)
      Apply a multiplier to a number value.
      Parameters:
      value - the source number
      multiple - the value to multiply value by; if null then value is returned unchanged
      Returns:
      the value, or null if value is null
      Since:
      1.3

    • offset

      public static Number offset(Number value, BigDecimal offset)
      Apply an offset to a number value.
      Parameters:
      value - the number to apply the offset to
      offset - the value to add to value; if null then value is returned unchanged
      Returns:
      the value, or null if value is null
      Since:
      1.3

    • bigIntegerForBitSet

      public static BigInteger bigIntegerForBitSet(BitSet bs)
      Get an integer for a BitSet.
      Parameters:
      bs - the bit set to convert to an integer representation
      Returns:
      the integer, never null
      Since:
      1.4

    • bitSetForBigInteger

      public static BitSet bitSetForBigInteger(BigInteger value)
      Get a BitSet for an integer.
      Parameters:
      value - the integer to convert to a BitSet
      Returns:
      a BitSet with all set bits of value set; never null
      Throws:
      IllegalArgumentException - if value is negative

    • getAndIncrementWithWrap

      public static int getAndIncrementWithWrap(AtomicInteger n, int restart)
      Increment and return the value from n, wrapping to restart after Integer.MAX_VALUE.
      Parameters:
      n - the atomic number
      restart - the value to wrap around to if Integer.MAX_VALUE is returned
      Returns:
      the incremented value, possibly wrapped around
      Since:
      1.7

    • getAndIncrementWithWrap

      public static long getAndIncrementWithWrap(AtomicLong n, long restart)
      Increment and return the value from n, wrapping to restart after Long.MAX_VALUE.
      Parameters:
      n - the atomic number
      restart - the value to wrap around to if Long.MAX_VALUE is returned
      Returns:
      the incremented value, possibly wrapped around
      Since:
      1.7

    • parseNumber

      public static Number parseNumber(String numberString, Class<? extends Number> numberType)
      Parse a String into a Number of a specific type.
      Parameters:
      numberString - the String to parse
      numberType - the type of Number to return
      Returns:
      the new Number instance
      Since:
      1.8

    • divide

      public static Number divide(Number dividend, Number divisor, Class<?> numberType)
      Divide two Number instances using a specific implementation of Number.

      Really the numberType argument should be considered a Class<? extends Number> but to simplify calling this method any Class is allowed.

      Parameters:
      dividend - the dividend value
      divisor - the divisor value
      numberType - the type of Number to treat the dividend and divisor as
      Returns:
      a Number instance of type numberType
      Since:
      1.8

    • subtract

      public static Number subtract(Number start, Number offset)
      Subtract two Number instances.

      The returned Number will be an instance of the start class.

      Parameters:
      start - the starting number to subtract from
      offset - the amount to subtract
      Returns:
      a Number instance of the same type as start
      Since:
      1.8

    • multiply

      public static Number multiply(Number a, Number b)
      Multiply two Number instances.

      The returned Number will be an instance of the a class.

      Parameters:
      a - first number
      b - second number
      Returns:
      a Number instance of the same type as a
      Since:
      1.8

    • humanReadableCount

      public static String humanReadableCount(long count)
      Format a count in a "human readable" format, with progressively larger SI units.

      For example this method will return 7.1 MB for input of 7077888.

      Adapted from @aioobe on Stack Overflow

      Parameters:
      count - the count to format
      Returns:
      the count formatted as a string
      Since:
      1.9

    • min

      public static Number min(Number n1, Number n2)
      Return the minimum between two number values.
      Parameters:
      n1 - the first number
      n2 - the second number
      Returns:
      the minimum number, or null if both arguments are null
      Since:
      1.10

    • max

      public static Number max(Number n1, Number n2)
      Return the maximum between two number values.
      Parameters:
      n1 - the first number
      n2 - the second number
      Returns:
      the maximum number, or null if both arguments are null
      Since:
      1.10

    • down

      public static Number down(Number n, Number significance)
      Round a number towards zero to the nearest integer multiple of a specific significance.

      This method rounds using the RoundingMode.DOWN mode.

      Parameters:
      n - the number to round
      significance - the multiple factor to round to
      Returns:
      the rounded number as a BigDecimal, or null if n or significance are null
      Since:
      1.10
      See Also:

    • up

      public static Number up(Number n, Number significance)
      Round a number towards zero to the nearest integer multiple of a specific significance.

      This method rounds using the RoundingMode.UP mode.

      Parameters:
      n - the number to round
      significance - the multiple factor to round to
      Returns:
      the rounded number as a BigDecimal, or null if n or significance are null
      Since:
      1.10
      See Also:

    • floor

      public static Number floor(Number n, Number significance)
      Round positive numbers towards zero and negative numbers away from zero, to the nearest integer multiple of a specific significance.

      This method rounds using the RoundingMode.FLOOR mode.

      Parameters:
      n - the number to round
      significance - the multiple factor to round to
      Returns:
      the rounded number as a BigDecimal, or null if n or significance are null
      Since:
      1.10
      See Also:

    • ceil

      public static Number ceil(Number n, Number significance)
      Round positive numbers away from zero and negative numbers towards zero, to the nearest integer multiple of a specific significance.

      This method rounds using the RoundingMode.CEILING mode.

      Parameters:
      n - the number to round
      significance - the multiple factor to round to
      Returns:
      the rounded number as a BigDecimal, or null if n or significance are null
      Since:
      1.10
      See Also:

    • mround

      public static Number mround(Number n, Number significance)
      Round a number to the nearest integer multiple of a specific significance.

      This method rounds using the RoundingMode.HALF_UP mode.

      Parameters:
      n - the number to round
      significance - the multiple factor to round to
      Returns:
      the rounded number as a BigDecimal, or null if n or significance are null
      Since:
      1.10
      See Also:

    • mround

      public static Number mround(Number n, Number significance, RoundingMode mode)
      Round a number to the nearest integer multiple of a specific significance using a specific rounding mode.

      This method supports rounding like supported by common spreadsheet application formulas CEILING, FLOOR, and MROUND, which accept a significance factor to round to.

      Parameters:
      n - the number to round
      significance - the multiple factor to round to
      mode - the rounding mode to use
      Returns:
      the rounded number as a BigDecimal, or null if n or significance are null
      Since:
      1.10

    • round

      public static Number round(Number n, Number digits)
      Round a number to a maximum number of decimal digits using the RoundingMode.HALF_UP mode.
      Parameters:
      n - the number to round
      digits - the maximum number of decimal digits
      Returns:
      the rounded number as a BigDecimal, or null if n or digits is null
      Since:
      1.10
      See Also:

    • roundUp

      public static Number roundUp(Number n, Number digits)
      Round a number away from zero to a maximum number of decimal digits.
      Parameters:
      n - the number to round
      digits - the maximum number of decimal digits
      Returns:
      the rounded number as a BigDecimal, or null if n or digits is null
      Since:
      1.10
      See Also:

    • roundDown

      public static Number roundDown(Number n, Number digits)
      Round a number towards zero to a maximum number of decimal digits.
      Parameters:
      n - the number to round
      digits - the maximum number of decimal digits
      Returns:
      the rounded number as a BigDecimal, or null if n or digits is null
      Since:
      1.10
      See Also:

    • round

      public static Number round(Number n, Number digits, RoundingMode mode)
      Round a number to a maximum number of decimal digits.
      Parameters:
      n - the number to round
      digits - the maximum number of decimal digits
      mode - the rounding mode
      Returns:
      the rounded number as a BigDecimal, or null if n or digits is null
      Since:
      1.10

    • narrow

      public static Number narrow(Number n, int minBytePower)
      Narrow a number to the smallest possible number type that can exactly represent the given number.

      If n cannot be narrowed then n is returned.

      Parameters:
      n - the number to narrow
      minBytePower - a minimum power-of-two byte size to narrow to; to; for example 1 would narrow to at most a Short, 2 to at most an Integer or Float, 3 to at most a Long or Double
      Returns:
      the (possibly) narrowed number, or null if n is null
      Since:
      1.10

    • narrow

      public static Number narrow(BigInteger n, int minBytePower)
      Narrow a BigInteger to the smallest possible number type that can exactly represent the given number.

      If n cannot be narrowed then n is returned.

      Parameters:
      n - the number to narrow
      minBytePower - a minimum power-of-two byte size to narrow to; to; for example 1 would narrow to at most a Short, 2 to at most an Integer or Float, 3 to at most a Long or Double
      Returns:
      the (possibly) narrowed number, or null if n is null
      Since:
      1.10

    • narrow

      public static Number narrow(BigDecimal n, int minBytePower)
      Narrow a BigDecimal to the smallest possible number type that can exactly represent the given number.

      If n cannot be narrowed then n is returned.

      Parameters:
      n - the number to narrow
      minBytePower - a minimum power-of-two byte size to narrow to; to; for example 1 would narrow to at most a Short, 2 to at most an Integer or Float, 3 to at most a Long or Double
      Returns:
      the (possibly) narrowed number, or null if n is null
      Since:
      1.10

    • floatValueExact

      public static Float floatValueExact(BigDecimal n)
      Attempt to convert a BigDecimal exactly to a float.
      Parameters:
      n - the number to convert
      Returns:
      the converted value, or null if n is null
      Throws:
      ArithmeticException - if an exact conversion cannot be done
      Since:
      1.10

    • doubleValueExact

      public static Double doubleValueExact(BigDecimal n)
      Attempt to convert a BigDecimal exactly to a double.
      Parameters:
      n - the number to convert
      Returns:
      the converted value, or null if n is null
      Throws:
      ArithmeticException - if an exact conversion cannot be done
      Since:
      1.10