Package net.jafama

Class NumbersUtils


  • public final class NumbersUtils
    extends java.lang.Object
    Class containing various basic utility methods to deal with numbers. This class is meant to be light (no big look-up tables or such). Check methods return boolean if success, for it allows to use them in assertions. toString methods use capital letters, unlike JDK's toStrings, for it is more readable (especially, "l" and "1" can easily be confused with one another). Some methods have an int version additionally to the long version, even though long version could be used instead, for performance reasons, either for the methods themselves (if they do computations with ints instead of longs), or to be used in an int use case (like methods checking whether or not a signed int can fit in such number of bits).
    • Field Detail

      • DOUBLE_MIN_NORMAL

        public static final double DOUBLE_MIN_NORMAL
        Double.MIN_NORMAL since Java 6.
      • FLOAT_MIN_NORMAL

        public static final float FLOAT_MIN_NORMAL
        Float.MIN_NORMAL since Java 6.
      • CHAR_BY_DIGIT

        private static final char[] CHAR_BY_DIGIT
        All possible upper case chars for representing a number as a String.
      • DIV_SHIFT_BY_RADIX

        private static final int[] DIV_SHIFT_BY_RADIX
        For power-of-two radixes only.
      • MAX_NBR_OF_NEG_INT_DIGITS_BY_RADIX

        private static final int[] MAX_NBR_OF_NEG_INT_DIGITS_BY_RADIX
      • MAX_NBR_OF_NEG_LONG_DIGITS_BY_RADIX

        private static final int[] MAX_NBR_OF_NEG_LONG_DIGITS_BY_RADIX
      • PIO2_HI

        private static final double PIO2_HI
      • PIO2_LO

        private static final double PIO2_LO
      • PI_HI

        private static final double PI_HI
      • PI_LO

        private static final double PI_LO
      • TWOPI_HI

        private static final double TWOPI_HI
      • TWOPI_LO

        private static final double TWOPI_LO
    • Constructor Detail

      • NumbersUtils

        private NumbersUtils()
    • Method Detail

      • equal

        public static boolean equal​(float a,
                                    float b)
        Returns:
        True if the specified values are equal or both NaN, false otherwise.
      • equal

        public static boolean equal​(double a,
                                    double b)
        Returns:
        True if the specified values are equal or both NaN, false otherwise.
      • isMathematicalInteger

        public static boolean isMathematicalInteger​(float value)
        Returns:
        True if the specified value is a mathematical integer, false otherwise (which includes NaN and +-Infinity).
      • isMathematicalInteger

        public static boolean isMathematicalInteger​(double value)
        Returns:
        True if the specified value is a mathematical integer, false otherwise (which includes NaN and +-Infinity).
      • isEquidistant

        public static boolean isEquidistant​(float value)
        Parameters:
        value - A float value.
        Returns:
        True if the specified value is equidistant from two adjacent mathematical integers, false otherwise (which includes NaN and +-Infinity).
      • isEquidistant

        public static boolean isEquidistant​(double value)
        Parameters:
        value - A double value.
        Returns:
        True if the specified value is equidistant from two adjacent mathematical integers, false otherwise (which includes NaN and +-Infinity).
      • isNaNOrInfinite

        public static boolean isNaNOrInfinite​(float a)
        Parameters:
        value - A float value.
        Returns:
        True if the specified value is NaN or +-Infinity, false otherwise.
      • isNaNOrInfinite

        public static boolean isNaNOrInfinite​(double a)
        Parameters:
        value - A double value.
        Returns:
        True if the specified value is NaN or +-Infinity, false otherwise.
      • signFromBit

        public static int signFromBit​(float value)
        Parameters:
        value - A float value.
        Returns:
        -1 if sign bit is 1, 1 if sign bit is 0.
      • signFromBit

        public static long signFromBit​(double value)
        Parameters:
        value - A double value.
        Returns:
        -1 if sign bit is 1, 1 if sign bit is 0.
      • isInRange

        public static boolean isInRange​(int min,
                                        int max,
                                        int a)
        Returns:
        True if the specified value is in the specified range (inclusive), false otherwise.
      • isInRange

        public static boolean isInRange​(long min,
                                        long max,
                                        long a)
        Returns:
        True if the specified value is in the specified range (inclusive), false otherwise.
      • isInRange

        public static boolean isInRange​(float min,
                                        float max,
                                        float a)
        Returns false if any value is NaN.
        Returns:
        True if the specified value is in the specified range (inclusive), false otherwise.
      • isInRange

        public static boolean isInRange​(double min,
                                        double max,
                                        double a)
        Returns false if any value is NaN.
        Returns:
        True if the specified value is in the specified range (inclusive), false otherwise.
      • checkIsInRange

        public static boolean checkIsInRange​(int min,
                                             int max,
                                             int a)
        Returns:
        True if does not throw.
        Throws:
        java.lang.IllegalArgumentException - if the specified value is not in the specified range (inclusive).
      • checkIsInRange

        public static boolean checkIsInRange​(long min,
                                             long max,
                                             long a)
        Returns:
        True if does not throw.
        Throws:
        java.lang.IllegalArgumentException - if the specified value is not in the specified range (inclusive).
      • checkIsInRange

        public static boolean checkIsInRange​(float min,
                                             float max,
                                             float a)
        Returns:
        True if does not throw.
        Throws:
        java.lang.IllegalArgumentException - if the specified value is not in the specified range (inclusive) or any parameter is NaN.
      • checkIsInRange

        public static boolean checkIsInRange​(double min,
                                             double max,
                                             double a)
        Returns:
        True if does not throw.
        Throws:
        java.lang.IllegalArgumentException - if the specified value is not in the specified range (inclusive) or any parameter is NaN.
      • toRange

        public static int toRange​(int min,
                                  int max,
                                  int a)
        Parameters:
        min - A value.
        max - A value.
        a - A value.
        Returns:
        min if a <= min, else max if a >= max, else a.
      • toRange

        public static long toRange​(long min,
                                   long max,
                                   long a)
        Parameters:
        min - A value.
        max - A value.
        a - A value.
        Returns:
        min if a <= min, else max if a >= max, else a.
      • toRange

        public static float toRange​(float min,
                                    float max,
                                    float a)
        Parameters:
        min - A value.
        max - A value.
        a - A value.
        Returns:
        min if a <= min, else max if a >= max, else a.
      • toRange

        public static double toRange​(double min,
                                     double max,
                                     double a)
        Parameters:
        min - A value.
        max - A value.
        a - A value.
        Returns:
        min if a <= min, else max if a >= max, else a.
      • isInRangeSigned

        public static boolean isInRangeSigned​(int a,
                                              int bitSize)
        Parameters:
        bitSize - A number of bits, in [1,32].
        Returns:
        True if the specified value fits as a signed integer over the specified number of bits, false otherwise.
        Throws:
        java.lang.IllegalArgumentException - if the specified number of bits is not in [1,32].
      • isInRangeSigned

        public static boolean isInRangeSigned​(long a,
                                              int bitSize)
        Parameters:
        bitSize - A number of bits, in [1,64].
        Returns:
        True if the specified value fits as a signed integer over the specified number of bits, false otherwise.
        Throws:
        java.lang.IllegalArgumentException - if the specified number of bits is not in [1,64].
      • isInRangeUnsigned

        public static boolean isInRangeUnsigned​(int a,
                                                int bitSize)
        Parameters:
        bitSize - A number of bits, in [1,31].
        Returns:
        True if the specified value fits as an unsigned integer over the specified number of bits, false otherwise.
        Throws:
        java.lang.IllegalArgumentException - if the specified number of bits is not in [1,31].
      • isInRangeUnsigned

        public static boolean isInRangeUnsigned​(long a,
                                                int bitSize)
        Parameters:
        bitSize - A number of bits, in [1,63].
        Returns:
        True if the specified value fits as an unsigned integer over the specified number of bits, false otherwise.
        Throws:
        java.lang.IllegalArgumentException - if the specified number of bits is not in [1,63].
      • checkIsInRangeSigned

        public static boolean checkIsInRangeSigned​(int a,
                                                   int bitSize)
        Parameters:
        bitSize - A number of bits, in [1,32].
        Returns:
        True if does not throw.
        Throws:
        java.lang.IllegalArgumentException - if the specified value does not fit as a signed integer over the specified number of bits.
      • checkIsInRangeSigned

        public static boolean checkIsInRangeSigned​(long a,
                                                   int bitSize)
        Parameters:
        bitSize - A number of bits, in [1,64].
        Returns:
        True if does not throw.
        Throws:
        java.lang.IllegalArgumentException - if the specified value does not fit as a signed integer over the specified number of bits.
      • checkIsInRangeUnsigned

        public static boolean checkIsInRangeUnsigned​(int a,
                                                     int bitSize)
        Parameters:
        bitSize - A number of bits, in [1,31].
        Returns:
        True if does not throw.
        Throws:
        java.lang.IllegalArgumentException - if the specified value does not fit as an unsigned integer over the specified number of bits.
      • checkIsInRangeUnsigned

        public static boolean checkIsInRangeUnsigned​(long a,
                                                     int bitSize)
        Parameters:
        bitSize - A number of bits, in [1,63].
        Returns:
        True if does not throw.
        Throws:
        java.lang.IllegalArgumentException - if the specified value does not fit as an unsigned integer over the specified number of bits.
      • intMaskMSBits0

        public static int intMaskMSBits0​(int bitSize)
        Parameters:
        bitSize - A number of bits, in [0,32].
        Returns:
        Mask with the specified number of left bits set with 0, and other bits set with 1.
      • intMaskMSBits1

        public static int intMaskMSBits1​(int bitSize)
        Parameters:
        bitSize - A number of bits, in [0,32].
        Returns:
        Mask with the specified number of left bits set with 1, and other bits set with 0.
      • intMaskLSBits0

        public static int intMaskLSBits0​(int bitSize)
        Parameters:
        bitSize - A number of bits, in [0,32].
        Returns:
        Mask with the specified number of right bits set with 0, and other bits set with 1.
      • intMaskLSBits1

        public static int intMaskLSBits1​(int bitSize)
        Parameters:
        bitSize - A number of bits, in [0,32].
        Returns:
        Mask with the specified number of right bits set with 1, and other bits set with 0.
      • longMaskMSBits0

        public static long longMaskMSBits0​(int bitSize)
        Parameters:
        bitSize - A number of bits, in [0,64].
        Returns:
        Mask with the specified number of left bits set with 0, and other bits set with 1.
      • longMaskMSBits1

        public static long longMaskMSBits1​(int bitSize)
        Parameters:
        bitSize - A number of bits, in [0,64].
        Returns:
        Mask with the specified number of left bits set with 1, and other bits set with 0.
      • longMaskLSBits0

        public static long longMaskLSBits0​(int bitSize)
        Parameters:
        bitSize - A number of bits, in [0,64].
        Returns:
        Mask with the specified number of right bits set with 0, and other bits set with 1.
      • longMaskLSBits1

        public static long longMaskLSBits1​(int bitSize)
        Parameters:
        bitSize - A number of bits, in [0,64].
        Returns:
        Mask with the specified number of right bits set with 1, and other bits set with 0.
      • byteAsUnsigned

        public static short byteAsUnsigned​(byte value)
        Returns:
        Unsigned value corresponding to bits of the specified byte.
      • shortAsUnsigned

        public static int shortAsUnsigned​(short value)
        Returns:
        Unsigned value corresponding to bits of the specified short.
      • intAsUnsigned

        public static long intAsUnsigned​(int value)
        Returns:
        Unsigned value corresponding to bits of the specified int.
      • isValidBitSizeForSignedInt

        public static boolean isValidBitSizeForSignedInt​(int bitSize)
        Returns:
        True if a signed int value can be read over the specified number of bits, i.e. if it is in [1,32], false otherwise.
      • isValidBitSizeForSignedLong

        public static boolean isValidBitSizeForSignedLong​(int bitSize)
        Returns:
        True if a signed long value can be read over the specified number of bits, i.e. if it is in [1,64], false otherwise.
      • isValidBitSizeForUnsignedInt

        public static boolean isValidBitSizeForUnsignedInt​(int bitSize)
        Returns:
        True if an unsigned int value can be read over the specified number of bits, i.e. if it is in [1,31], false otherwise.
      • isValidBitSizeForUnsignedLong

        public static boolean isValidBitSizeForUnsignedLong​(int bitSize)
        Returns:
        True if an unsigned long value can be read over the specified number of bits, i.e. if it is in [1,63], false otherwise.
      • checkBitSizeForSignedInt

        public static boolean checkBitSizeForSignedInt​(int bitSize)
        Returns:
        True if does not throw.
        Throws:
        java.lang.IllegalArgumentException - if a signed int value can't be read over the specified number of bits, i.e. if it is not in [1,32].
      • checkBitSizeForSignedLong

        public static boolean checkBitSizeForSignedLong​(int bitSize)
        Returns:
        True if does not throw.
        Throws:
        java.lang.IllegalArgumentException - if a signed long value can't be read over the specified number of bits, i.e. if it is not in [1,64].
      • checkBitSizeForUnsignedInt

        public static boolean checkBitSizeForUnsignedInt​(int bitSize)
        Returns:
        True if does not throw.
        Throws:
        java.lang.IllegalArgumentException - if an unsigned int value can't be read over the specified number of bits, i.e. if it is not in [1,31].
      • checkBitSizeForUnsignedLong

        public static boolean checkBitSizeForUnsignedLong​(int bitSize)
        Returns:
        True if does not throw.
        Throws:
        java.lang.IllegalArgumentException - if an unsigned long value can't be read over the specified number of bits, i.e. if it is not in [1,63].
      • minSignedIntForBitSize

        public static int minSignedIntForBitSize​(int bitSize)
        Parameters:
        bitSize - A number of bits in [1,32].
        Returns:
        The min signed int value that can be stored over the specified number of bits.
        Throws:
        java.lang.IllegalArgumentException - if the specified number of bits is out of range.
      • minSignedLongForBitSize

        public static long minSignedLongForBitSize​(int bitSize)
        Parameters:
        bitSize - A number of bits in [1,64].
        Returns:
        The min signed long value that can be stored over the specified number of bits.
        Throws:
        java.lang.IllegalArgumentException - if the specified number of bits is out of range.
      • maxSignedIntForBitSize

        public static int maxSignedIntForBitSize​(int bitSize)
        Parameters:
        bitSize - A number of bits in [1,32].
        Returns:
        The max signed int value that can be stored over the specified number of bits.
        Throws:
        java.lang.IllegalArgumentException - if the specified number of bits is out of range.
      • maxSignedLongForBitSize

        public static long maxSignedLongForBitSize​(int bitSize)
        Parameters:
        bitSize - A number of bits in [1,64].
        Returns:
        The max signed long value that can be stored over the specified number of bits.
        Throws:
        java.lang.IllegalArgumentException - if the specified number of bits is out of range.
      • maxUnsignedIntForBitSize

        public static int maxUnsignedIntForBitSize​(int bitSize)
        Parameters:
        bitSize - A number of bits in [1,31].
        Returns:
        The max unsigned int value that can be stored over the specified number of bits.
        Throws:
        java.lang.IllegalArgumentException - if the specified number of bits is out of range.
      • maxUnsignedLongForBitSize

        public static long maxUnsignedLongForBitSize​(int bitSize)
        Parameters:
        bitSize - A number of bits in [1,63].
        Returns:
        The max unsigned long value that can be stored over the specified number of bits.
        Throws:
        java.lang.IllegalArgumentException - if the specified number of bits is out of range.
      • bitSizeForSignedValue

        public static int bitSizeForSignedValue​(int value)
        Returns:
        The number of bits required to store the specified value as a signed integer, i.e. a result in [1,32].
      • bitSizeForSignedValue

        public static int bitSizeForSignedValue​(long value)
        Returns:
        The number of bits required to store the specified value as a signed integer, i.e. a result in [1,64].
      • bitSizeForUnsignedValue

        public static int bitSizeForUnsignedValue​(int value)
        Parameters:
        value - An integer value in [0,Integer.MAX_VALUE].
        Returns:
        The number of bits required to store the specified value as an unsigned integer, i.e. a result in [1,31].
        Throws:
        java.lang.IllegalArgumentException - if the specified value is < 0.
      • bitSizeForUnsignedValue

        public static int bitSizeForUnsignedValue​(long value)
        Parameters:
        value - An integer value in [0,Long.MAX_VALUE].
        Returns:
        The number of bits required to store the specified value as an unsigned integer, i.e. a result in [1,63].
        Throws:
        java.lang.IllegalArgumentException - if the specified value is < 0.
      • signum

        public static int signum​(int a)
        Returns:
        1 if the specified value is > 0, 0 if it is 0, -1 otherwise.
      • signum

        public static int signum​(long a)
        Returns:
        1 if the specified value is > 0, 0 if it is 0, -1 otherwise.
      • isEven

        public static boolean isEven​(int a)
        Returns:
        True if the specified value is even, false otherwise.
      • isEven

        public static boolean isEven​(long a)
        Returns:
        True if the specified value is even, false otherwise.
      • isOdd

        public static boolean isOdd​(int a)
        Returns:
        True if the specified value is odd, false otherwise.
      • isOdd

        public static boolean isOdd​(long a)
        Returns:
        True if the specified value is odd, false otherwise.
      • haveSameEvenness

        public static boolean haveSameEvenness​(int a,
                                               int b)
        Returns:
        True if the specified values are both even or both odd, false otherwise.
      • haveSameEvenness

        public static boolean haveSameEvenness​(long a,
                                               long b)
        Returns:
        True if the specified values are both even or both odd, false otherwise.
      • haveSameSign

        public static boolean haveSameSign​(int a,
                                           int b)
        Returns:
        True if the specified values are both >= 0 or both < 0, false otherwise.
      • haveSameSign

        public static boolean haveSameSign​(long a,
                                           long b)
        Returns:
        True if the specified values are both >= 0 or both < 0, false otherwise.
      • isPowerOfTwo

        public static boolean isPowerOfTwo​(int a)
        Returns:
        True if the specified value is a power of two, i.e. a value of the form 2^k, with k >= 0.
      • isPowerOfTwo

        public static boolean isPowerOfTwo​(long a)
        Returns:
        True if the specified value is a power of two, i.e. a value of the form 2^k, with k >= 0.
      • isSignedPowerOfTwo

        public static boolean isSignedPowerOfTwo​(int a)
        Returns:
        True if the specified value is a signed power of two, i.e. a value of the form +-2^k, with k >= 0.
      • isSignedPowerOfTwo

        public static boolean isSignedPowerOfTwo​(long a)
        Returns:
        True if the specified value is a signed power of two, i.e. a value of the form +-2^k, with k >= 0.
      • floorPowerOfTwo

        public static int floorPowerOfTwo​(int a)
        Parameters:
        a - A value in [1,Integer.MAX_VALUE].
        Returns:
        The highest power of two <= a.
      • floorPowerOfTwo

        public static long floorPowerOfTwo​(long a)
        Parameters:
        a - A value in [1,Long.MAX_VALUE].
        Returns:
        The highest power of two <= a.
      • ceilingPowerOfTwo

        public static int ceilingPowerOfTwo​(int a)
        Parameters:
        a - A value in [0,2^30].
        Returns:
        The lowest power of two >= a.
      • ceilingPowerOfTwo

        public static long ceilingPowerOfTwo​(long a)
        Parameters:
        a - A value in [0,2^62].
        Returns:
        The lowest power of two >= a.
      • meanLow

        public static int meanLow​(int a,
                                  int b)
        Returns:
        Mean without overflow, rounded to the lowest value (i.e. mathematical floor((a+b)/2), using floating point division).
      • meanLow

        public static long meanLow​(long a,
                                   long b)
        Returns:
        Mean without overflow, rounded to the lowest value (i.e. mathematical floor((a+b)/2), using floating point division).
      • meanSml

        public static int meanSml​(int a,
                                  int b)
        Returns:
        Mean without overflow, rounded to the value of smallest magnitude (i.e. mathematical (a+b)/2, using integer division).
      • meanSml

        public static long meanSml​(long a,
                                   long b)
        Returns:
        Mean without overflow, rounded to the value of smallest magnitude (i.e. mathematical (a+b)/2, using integer division).
      • negHalfWidth

        public static int negHalfWidth​(int min,
                                       int max)
        Useful because a positive int value could not represent half the width of full int range width, which is mathematically Integer.MAX_VALUE+1.
        Returns:
        Minus half the range width (inclusive, and rounded to the value of smaller magnitude) between the specified bounds.
        Throws:
        java.lang.IllegalArgumentException - if min > max.
      • negHalfWidth

        public static long negHalfWidth​(long min,
                                        long max)
        Useful because a positive long value could not represent half the width of full long range width, which is mathematically Long.MAX_VALUE+1.
        Returns:
        Minus half the range width (inclusive, and rounded to the value of smaller magnitude) between the specified bounds.
        Throws:
        java.lang.IllegalArgumentException - if min > max.
      • moduloSignedPowerOfTwo

        public static int moduloSignedPowerOfTwo​(int value,
                                                 int spot)
        This treatment being designed for optimization, the fact that spot is a signed power of two is not checked.
        Parameters:
        value - A value.
        spot - A signed power of two (i.e. a value of the form +-2^k, k >= 0).
        Returns:
        value % spot, i.e. a value in ]-|spot|,|spot|[.
      • moduloSignedPowerOfTwo

        public static long moduloSignedPowerOfTwo​(long value,
                                                  long spot)
        This treatment being designed for optimization, the fact that spot is a signed power of two is not checked.
        Parameters:
        value - A value.
        spot - A signed power of two (i.e. a value of the form +-2^k, k >= 0).
        Returns:
        value % spot, i.e. a value in ]-|spot|,|spot|[.
      • log2

        public static int log2​(int value)
        Parameters:
        value - An integer value > 0.
        Returns:
        The integer part of the logarithm, in base 2, of the specified value, i.e. a result in [0,30]
        Throws:
        java.lang.IllegalArgumentException - if the specified value is <= 0.
      • log2

        public static int log2​(long value)
        Parameters:
        value - An integer value > 0.
        Returns:
        The integer part of the logarithm, in base 2, of the specified value, i.e. a result in [0,62]
        Throws:
        java.lang.IllegalArgumentException - if the specified value is <= 0.
      • abs

        public static int abs​(int a)
        Possibly faster than java.lang.Math.abs(int).
        Returns:
        The absolute value, except if value is Integer.MIN_VALUE, for which it returns Integer.MIN_VALUE.
      • abs

        public static long abs​(long a)
        Possibly faster than java.lang.Math.abs(long).
        Returns:
        The absolute value, except if value is Long.MIN_VALUE, for which it returns Long.MIN_VALUE.
      • absNeg

        public static int absNeg​(int a)
        Returns:
        The negative of the absolute value (always exact).
      • absNeg

        public static long absNeg​(long a)
        Returns:
        The negative of the absolute value (always exact).
      • intHash

        public static int intHash​(long a)
        If the specified value is in int range, the returned value is identical.
        Returns:
        An int hash of the specified value.
      • asByte

        public static byte asByte​(int a)
        Not defining an asByte(long) method, since asByte((int)aLong) works.
        Parameters:
        a - An int value.
        Returns:
        The specified value as byte.
        Throws:
        java.lang.ArithmeticException - if the specified value is not in [Byte.MIN_VALUE,Byte.MAX_VALUE] range.
      • asInt

        public static int asInt​(long a)
        Parameters:
        a - A long value.
        Returns:
        The specified value as int.
        Throws:
        java.lang.ArithmeticException - if the specified value is not in [Integer.MIN_VALUE,Integer.MAX_VALUE] range.
      • toInt

        public static int toInt​(long a)
        Parameters:
        a - A long value.
        Returns:
        The closest int value in [Integer.MIN_VALUE,Integer.MAX_VALUE] range.
      • plusExact

        public static int plusExact​(int a,
                                    int b)
        Parameters:
        a - An int value.
        b - An int value.
        Returns:
        The mathematical result of a+b.
        Throws:
        java.lang.ArithmeticException - if the mathematical result of a+b is not in [Integer.MIN_VALUE,Integer.MAX_VALUE] range.
      • plusExact

        public static long plusExact​(long a,
                                     long b)
        Parameters:
        a - A long value.
        b - A long value.
        Returns:
        The mathematical result of a+b.
        Throws:
        java.lang.ArithmeticException - if the mathematical result of a+b is not in [Long.MIN_VALUE,Long.MAX_VALUE] range.
      • plusBounded

        public static int plusBounded​(int a,
                                      int b)
        Parameters:
        a - An int value.
        b - An int value.
        Returns:
        The int value of [Integer.MIN_VALUE,Integer.MAX_VALUE] range which is the closest to mathematical result of a+b.
      • plusBounded

        public static long plusBounded​(long a,
                                       long b)
        Parameters:
        a - A long value.
        b - A long value.
        Returns:
        The long value of [Long.MIN_VALUE,Long.MAX_VALUE] range which is the closest to mathematical result of a+b.
      • minusExact

        public static int minusExact​(int a,
                                     int b)
        Parameters:
        a - An int value.
        b - An int value.
        Returns:
        The mathematical result of a-b.
        Throws:
        java.lang.ArithmeticException - if the mathematical result of a-b is not in [Integer.MIN_VALUE,Integer.MAX_VALUE] range.
      • minusExact

        public static long minusExact​(long a,
                                      long b)
        Parameters:
        a - A long value.
        b - A long value.
        Returns:
        The mathematical result of a-b.
        Throws:
        java.lang.ArithmeticException - if the mathematical result of a-b is not in [Long.MIN_VALUE,Long.MAX_VALUE] range.
      • minusBounded

        public static int minusBounded​(int a,
                                       int b)
        Parameters:
        a - An int value.
        b - An int value.
        Returns:
        The int value of [Integer.MIN_VALUE,Integer.MAX_VALUE] range which is the closest to mathematical result of a-b.
      • minusBounded

        public static long minusBounded​(long a,
                                        long b)
        Parameters:
        a - A long value.
        b - A long value.
        Returns:
        The long value of [Long.MIN_VALUE,Long.MAX_VALUE] range which is the closest to mathematical result of a-b.
      • timesExact

        public static int timesExact​(int a,
                                     int b)
        Parameters:
        a - An int value.
        b - An int value.
        Returns:
        The mathematical result of a*b.
        Throws:
        java.lang.ArithmeticException - if the mathematical result of a*b is not in [Integer.MIN_VALUE,Integer.MAX_VALUE] range.
      • timesExact

        public static long timesExact​(long a,
                                      long b)
        Parameters:
        a - A long value.
        b - A long value.
        Returns:
        The mathematical result of a*b.
        Throws:
        java.lang.ArithmeticException - if the mathematical result of a*b is not in [Long.MIN_VALUE,Long.MAX_VALUE] range.
      • timesBounded

        public static int timesBounded​(int a,
                                       int b)
        Parameters:
        a - An int value.
        b - An int value.
        Returns:
        The int value of [Integer.MIN_VALUE,Integer.MAX_VALUE] range which is the closest to mathematical result of a*b.
      • timesBounded

        public static long timesBounded​(long a,
                                        long b)
        Parameters:
        a - A long value.
        b - A long value.
        Returns:
        The long value of [Long.MIN_VALUE,Long.MAX_VALUE] range which is the closest to mathematical result of a*b.
      • twoPow

        public static double twoPow​(int power)
        Returns the exact result, provided it's in double range, i.e. if power is in [-1074,1023].
        Parameters:
        power - An int power.
        Returns:
        2^power as a double, or +-Infinity in case of overflow.
      • twoPowAsIntExact

        public static int twoPowAsIntExact​(int power)
        Parameters:
        power - An int power.
        Returns:
        2^power as an int.
        Throws:
        java.lang.ArithmeticException - if the mathematical result is not in int range, i.e. if power is not in [0,30].
      • twoPowAsIntBounded

        public static int twoPowAsIntBounded​(int power)
        Parameters:
        power - An int power.
        Returns:
        2^power as an int, or the closest power of two in int range in case of overflow, i.e. if power is not in [0,30].
      • twoPowAsLongExact

        public static long twoPowAsLongExact​(int power)
        Parameters:
        power - An int power.
        Returns:
        2^power as a long.
        Throws:
        java.lang.ArithmeticException - if the mathematical result is not in long range, i.e. if power is not in [0,62].
      • twoPowAsLongBounded

        public static long twoPowAsLongBounded​(int power)
        Parameters:
        power - An int power.
        Returns:
        2^power as a long, or the closest power of two in long range in case of overflow, i.e. if power is not in [0,62].
      • pow2

        public static int pow2​(int a)
        Parameters:
        a - A value.
        Returns:
        a*a.
      • pow2

        public static long pow2​(long a)
        Parameters:
        a - A value.
        Returns:
        a*a.
      • pow2

        public static float pow2​(float a)
        Parameters:
        a - A value.
        Returns:
        a*a.
      • pow2_strict

        public static float pow2_strict​(float a)
        Strict version.
        Parameters:
        a - A value.
        Returns:
        a*a.
      • pow2

        public static double pow2​(double a)
        Parameters:
        a - A value.
        Returns:
        a*a.
      • pow2_strict

        public static double pow2_strict​(double a)
        Strict version.
        Parameters:
        a - A value.
        Returns:
        a*a.
      • pow3

        public static int pow3​(int a)
        Parameters:
        a - A value.
        Returns:
        a*a*a.
      • pow3

        public static long pow3​(long a)
        Parameters:
        a - A value.
        Returns:
        a*a*a.
      • pow3

        public static float pow3​(float a)
        Parameters:
        a - A value.
        Returns:
        a*a*a.
      • pow3_strict

        public static float pow3_strict​(float a)
        Strict version.
        Parameters:
        a - A value.
        Returns:
        a*a*a.
      • pow3

        public static double pow3​(double a)
        Parameters:
        a - A value.
        Returns:
        a*a*a.
      • pow3_strict

        public static double pow3_strict​(double a)
        Strict version.
        Parameters:
        a - A value.
        Returns:
        a*a*a.
      • plus2PI

        public static double plus2PI​(double angRad)
        Parameters:
        angRad - An angle, in radians.
        Returns:
        angRad + 2*PI, accurately computed.
      • plus2PI_strict

        public static double plus2PI_strict​(double angRad)
        Strict version.
        Parameters:
        angRad - An angle, in radians.
        Returns:
        angRad + 2*PI, accurately computed.
      • minus2PI

        public static double minus2PI​(double angRad)
        Parameters:
        angRad - An angle, in radians.
        Returns:
        angRad - 2*PI, accurately computed.
      • minus2PI_strict

        public static double minus2PI_strict​(double angRad)
        Strict version.
        Parameters:
        angRad - An angle, in radians.
        Returns:
        angRad - 2*PI, accurately computed.
      • plusPI

        public static double plusPI​(double angRad)
        Parameters:
        angRad - An angle, in radians.
        Returns:
        angRad + PI, accurately computed.
      • plusPI_strict

        public static double plusPI_strict​(double angRad)
        Strict version.
        Parameters:
        angRad - An angle, in radians.
        Returns:
        angRad + PI, accurately computed.
      • minusPI

        public static double minusPI​(double angRad)
        Parameters:
        angRad - An angle, in radians.
        Returns:
        angRad - PI, accurately computed.
      • minusPI_strict

        public static double minusPI_strict​(double angRad)
        Strict version.
        Parameters:
        angRad - An angle, in radians.
        Returns:
        angRad - PI, accurately computed.
      • plusPIO2

        public static double plusPIO2​(double angRad)
        Parameters:
        angRad - An angle, in radians.
        Returns:
        angRad + PI/2, accurately computed.
      • plusPIO2_strict

        public static double plusPIO2_strict​(double angRad)
        Strict version.
        Parameters:
        angRad - An angle, in radians.
        Returns:
        angRad + PI/2, accurately computed.
      • minusPIO2

        public static double minusPIO2​(double angRad)
        Parameters:
        angRad - An angle, in radians.
        Returns:
        angRad - PI/2, accurately computed.
      • minusPIO2_strict

        public static double minusPIO2_strict​(double angRad)
        Strict version.
        Parameters:
        angRad - An angle, in radians.
        Returns:
        angRad - PI/2, accurately computed.
      • checkRadix

        public static boolean checkRadix​(int radix)
        Parameters:
        radix - Radix to be checked.
        Returns:
        True if does not throw.
        Throws:
        java.lang.IllegalArgumentException - if the specified radix is not in [2,36].
      • computeNbrOfChars

        public static int computeNbrOfChars​(int value,
                                            int radix)
        Parameters:
        radix - A radix in [2,36].
        Returns:
        Number of characters (minus sign included) to represent the specified value in the specified radix.
      • computeNbrOfChars

        public static int computeNbrOfChars​(long value,
                                            int radix)
        Parameters:
        radix - A radix in [2,36].
        Returns:
        Number of characters (minus sign included) to represent the specified value in the specified radix.
      • computeNbrOfChars

        public static int computeNbrOfChars​(int value,
                                            int radix,
                                            int paddingUpTo)
        Parameters:
        radix - A radix in [2,36].
        paddingUpTo - Number of digits (sign excluded) up to which left-padding with zeros is done.
        Returns:
        Number of characters (minus sign included) to represent the specified value in the specified radix.
      • computeNbrOfChars

        public static int computeNbrOfChars​(long value,
                                            int radix,
                                            int paddingUpTo)
        Parameters:
        radix - A radix in [2,36].
        paddingUpTo - Number of digits (sign excluded) up to which left-padding with zeros is done.
        Returns:
        Number of characters (minus sign included) to represent the specified value in the specified radix.
      • computeNbrOfDigits

        public static int computeNbrOfDigits​(int value,
                                             int radix)
        Parameters:
        radix - A radix in [2,36].
        Returns:
        Number of digits of the specified value in the specified radix.
      • computeNbrOfDigits

        public static int computeNbrOfDigits​(long value,
                                             int radix)
        Parameters:
        radix - A radix in [2,36].
        Returns:
        Number of digits of the specified value in the specified radix.
      • computeNbrOfDigits

        public static int computeNbrOfDigits​(int value,
                                             int radix,
                                             int paddingUpTo)
        Parameters:
        radix - A radix in [2,36].
        paddingUpTo - Number of digits (sign excluded) up to which left-padding with zeros is done.
        Returns:
        Number of digits of the specified value in the specified radix, including the specified padding.
      • computeNbrOfDigits

        public static int computeNbrOfDigits​(long value,
                                             int radix,
                                             int paddingUpTo)
        Parameters:
        radix - A radix in [2,36].
        paddingUpTo - Number of digits (sign excluded) up to which left-padding with zeros is done.
        Returns:
        Number of digits of the specified value in the specified radix, including the specified padding.
      • toString

        public static java.lang.String toString​(int value)
        This method just delegates to Integer.toString(int), but is defined here to complete the API.
        Returns:
        String representation of the specified value in base 10.
      • toString

        public static java.lang.String toString​(long value)
        This method just delegates to Long.toString(long), but is defined here to complete the API.
        Returns:
        String representation of the specified value in base 10.
      • toString

        public static java.lang.String toString​(int value,
                                                int radix)
        Parameters:
        radix - A radix in [2,36].
        Returns:
        String representation of the specified value in the specified radix.
        Throws:
        java.lang.IllegalArgumentException - if the specified radix is out of range.
      • toString

        public static java.lang.String toString​(long value,
                                                int radix)
        Parameters:
        radix - A radix in [2,36].
        Returns:
        String representation of the specified value in the specified radix.
        Throws:
        java.lang.IllegalArgumentException - if the specified radix is out of range.
      • toString

        public static java.lang.String toString​(int value,
                                                int radix,
                                                int paddingUpTo)
        Parameters:
        radix - A radix in [2,36].
        paddingUpTo - Number of digits (sign excluded) up to which left-padding with zeros is done.
        Returns:
        String representation of the specified value in the specified radix.
        Throws:
        java.lang.IllegalArgumentException - if the specified radix is out of range.
      • toString

        public static java.lang.String toString​(long value,
                                                int radix,
                                                int paddingUpTo)
        Parameters:
        radix - A radix in [2,36].
        paddingUpTo - Number of digits (sign excluded) up to which left-padding with zeros is done.
        Returns:
        String representation of the specified value in the specified radix.
        Throws:
        java.lang.IllegalArgumentException - if the specified radix is out of range.
      • checkBitPositionsByte

        public static boolean checkBitPositionsByte​(int firstBitPos,
                                                    int lastBitPosExcl)
        Parameters:
        firstBitPos - First bit position (inclusive).
        lastBitPosExcl - Last bit position (exclusive).
        Returns:
        True if does not throw.
        Throws:
        java.lang.IllegalArgumentException - if the specified bit range does not fit in a byte.
      • checkBitPositionsShort

        public static boolean checkBitPositionsShort​(int firstBitPos,
                                                     int lastBitPosExcl)
        Parameters:
        firstBitPos - First bit position (inclusive).
        lastBitPosExcl - Last bit position (exclusive).
        Returns:
        True if does not throw.
        Throws:
        java.lang.IllegalArgumentException - if the specified bit range does not fit in a short.
      • checkBitPositionsInt

        public static boolean checkBitPositionsInt​(int firstBitPos,
                                                   int lastBitPosExcl)
        Parameters:
        firstBitPos - First bit position (inclusive).
        lastBitPosExcl - Last bit position (exclusive).
        Returns:
        True if does not throw.
        Throws:
        java.lang.IllegalArgumentException - if the specified bit range does not fit in an int.
      • checkBitPositionsLong

        public static boolean checkBitPositionsLong​(int firstBitPos,
                                                    int lastBitPosExcl)
        Parameters:
        firstBitPos - First bit position (inclusive).
        lastBitPosExcl - Last bit position (exclusive).
        Returns:
        True if does not throw.
        Throws:
        java.lang.IllegalArgumentException - if the specified bit range does not fit in a long.
      • toStringBits

        public static java.lang.String toStringBits​(byte bits)
        Returns:
        String representation of specified bits, in big endian.
      • toStringBits

        public static java.lang.String toStringBits​(short bits)
        Returns:
        String representation of specified bits, in big endian.
      • toStringBits

        public static java.lang.String toStringBits​(int bits)
        Returns:
        String representation of specified bits, in big endian.
      • toStringBits

        public static java.lang.String toStringBits​(long bits)
        Returns:
        String representation of specified bits, in big endian.
      • toStringBits

        public static java.lang.String toStringBits​(byte bits,
                                                    int firstBitPos,
                                                    int lastBitPosExcl,
                                                    boolean bigEndian,
                                                    boolean padding)
        Parameters:
        firstBitPos - First bit position (inclusive).
        lastBitPosExcl - Last bit position (exclusive).
        bigEndian - True for bits to be added in big endian order (MSBit to LSBit) false for little endian order.
        padding - True if underscores must be added instead of out-of-range bits, false to just add characters corresponding to in-range bits.
        Returns:
        String representation of specified bits.
      • toStringBits

        public static java.lang.String toStringBits​(short bits,
                                                    int firstBitPos,
                                                    int lastBitPosExcl,
                                                    boolean bigEndian,
                                                    boolean padding)
        Parameters:
        firstBitPos - First bit position (inclusive).
        lastBitPosExcl - Last bit position (exclusive).
        bigEndian - True for bits to be added in big endian order (MSBit to LSBit) false for little endian order.
        padding - True if underscores must be added instead of out-of-range bits, false to just add characters corresponding to in-range bits.
        Returns:
        String representation of specified bits.
      • toStringBits

        public static java.lang.String toStringBits​(int bits,
                                                    int firstBitPos,
                                                    int lastBitPosExcl,
                                                    boolean bigEndian,
                                                    boolean padding)
        Parameters:
        firstBitPos - First bit position (inclusive).
        lastBitPosExcl - Last bit position (exclusive).
        bigEndian - True for bits to be added in big endian order (MSBit to LSBit) false for little endian order.
        padding - True if underscores must be added instead of out-of-range bits, false to just add characters corresponding to in-range bits.
        Returns:
        String representation of specified bits.
      • toStringBits

        public static java.lang.String toStringBits​(long bits,
                                                    int firstBitPos,
                                                    int lastBitPosExcl,
                                                    boolean bigEndian,
                                                    boolean padding)
        Parameters:
        firstBitPos - First bit position (inclusive).
        lastBitPosExcl - Last bit position (exclusive).
        bigEndian - True for bits to be added in big endian order (MSBit to LSBit) false for little endian order.
        padding - True if underscores must be added instead of out-of-range bits, false to just add characters corresponding to in-range bits.
        Returns:
        String representation of specified bits.
      • toStringCSN

        public static java.lang.String toStringCSN​(double value)
        Parameters:
        value - A double value.
        Returns:
        String representing the specified value, using "computerized scientific notation", which Double.toString(double) uses for non-infinite values, when |value| < 1e-3 or |value| >= 1e7.
      • toStringNoCSN

        public static java.lang.String toStringNoCSN​(double value)
        Parameters:
        value - A double value.
        Returns:
        String representing the specified value, not in "computerized scientific notation", which Double.toString(double) uses for non-infinite values, when |value| < 1e-3 or |value| >= 1e7.
      • dontUseMe_isInNonEmptyRange_

        private static boolean dontUseMe_isInNonEmptyRange_​(int min,
                                                            int max,
                                                            int a)
        Had such isInXXX methods, and corresponding checkXXX methods, but they seem actually slower in practice, so just keeping this code here in case some day it becomes faster than regular isInXXX. Only works for non-empty ranges, i.e. such as min <= max. This treatment being designed for optimization, min <= max is not checked.
        Returns:
        True if the specified value is in the specified range (inclusive), false otherwise.
      • minSignedIntForBitSize_noCheck

        private static int minSignedIntForBitSize_noCheck​(int bitSize)
      • minSignedLongForBitSize_noCheck

        private static long minSignedLongForBitSize_noCheck​(int bitSize)
      • maxSignedIntForBitSize_noCheck

        private static int maxSignedIntForBitSize_noCheck​(int bitSize)
      • maxSignedLongForBitSize_noCheck

        private static long maxSignedLongForBitSize_noCheck​(int bitSize)
      • computeNbrOfDigits_negValue

        private static int computeNbrOfDigits_negValue​(int negValue,
                                                       int radix)
        Throws:
        java.lang.IllegalArgumentException - if the specified radix is out of range.
      • computeNbrOfDigits_negValue

        private static int computeNbrOfDigits_negValue​(long negValue,
                                                       int radix)
        Throws:
        java.lang.IllegalArgumentException - if the specified radix is out of range.
      • checkBitPositions

        private static boolean checkBitPositions​(int firstBitPos,
                                                 int lastBitPosExcl,
                                                 int bitSize)
      • toStringBits_0_32_bitPosAlreadyChecked

        private static java.lang.String toStringBits_0_32_bitPosAlreadyChecked​(int bitSize,
                                                                               int bits,
                                                                               int firstBitPos,
                                                                               int lastBitPosExcl,
                                                                               boolean bigEndian,
                                                                               boolean padding)
        Common method for byte, short and int. Could be a bit faster to have specific methods for byte and short, but not much, and that would also make more messy (byte-)code.
        Parameters:
        bitSize - Must be in [0,32].