Package org.apache.commons.rng.core.source64

Class LongJumpDistances

  • final class LongJumpDistances
extends java.lang.Object
    Utility for working with positive integer jump distances represented as 64-bit integers.
    Since:
    1.7

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private static long MANTISSA_MASK
      Mask to extract the 52-bit mantissa from a long representation of a double.
      private static int NAN_EXP
      The value of the exponent for NaN when the exponent is extracted and scaled to account for multiplying the floating-point 52-bit mantissa to an integer.
      private static int SMALL_SHIFT
      Small shift of a 53-bit significand where it remains within the same long.
      private static double TWO_POW_63
      2^63.

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private LongJumpDistances()
      Class contains only static methods.

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      (package private) static void validateJump​(double distance, double period)
      Validate the jump distance is valid within the given period of the cycle.
      (package private) static void validateJumpPowerOfTwo​(int logDistance, int logPeriod)
      Validate the jump distance of 2logDistance is valid within the given cycle period of 2logPeriod.
      (package private) static void writeUnsignedInteger​(double value, long[] result)
      Write the value to an unsigned integer representation.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • NAN_EXP

        private static final int NAN_EXP
        The value of the exponent for NaN when the exponent is extracted and scaled to account for multiplying the floating-point 52-bit mantissa to an integer. 1024 - 52 = 972.
        See Also:
        Constant Field Values

      • MANTISSA_MASK

        private static final long MANTISSA_MASK
        Mask to extract the 52-bit mantissa from a long representation of a double.
        See Also:
        Constant Field Values

      • SMALL_SHIFT

        private static final int SMALL_SHIFT
        Small shift of a 53-bit significand where it remains within the same long.
        See Also:
        Constant Field Values

    • Constructor Detail

      • LongJumpDistances

        private LongJumpDistances()
        Class contains only static methods.

    • Method Detail

      • validateJump

        static void validateJump​(double distance,
                         double period)
        Validate the jump distance is valid within the given period of the cycle.
        Parameters:
        distance - Jump distance.
        period - Cycle period.
        Throws:
        java.lang.IllegalArgumentException - if distance is negative, or is greater than the period.

      • validateJumpPowerOfTwo

        static void validateJumpPowerOfTwo​(int logDistance,
                                   int logPeriod)
        Validate the jump distance of 2logDistance is valid within the given cycle period of 2logPeriod.

        Note: Negative logDistance is allowed as the distance is >= 0.

        Parameters:
        logDistance - Base-2 logarithm of the distance to jump forward with the state cycle.
        logPeriod - Base-2 logarithm of the cycle period.
        Throws:
        java.lang.IllegalArgumentException - if logDistance >= logPeriod.

      • writeUnsignedInteger

        static void writeUnsignedInteger​(double value,
                                 long[] result)
        Write the value to an unsigned integer representation. Any fractional part of the floating-point value is discarded. The integer part of the value must be positive or an exception is raised.

        The 53-bit significand of the value is converted to an integer, shifted to align with a 64-bit boundary and written to the provided result, ordered with the least significant bits first.

        No bounds checking is performed. The result array is assumed to have a length of at least 1 to store an unshifted 53-bit significand. The required array size for values larger than 2^53 can be computed using: 

         1 + Math.getExponent(value) / 64

        Parts of the array not used by the significand are unchanged. It is recommended to use a newly created array for the result.

        Note: For jump distances validated as less than the period of an output cycle the result array length can be preallocated based on the maximum possible length.

        Parameters:
        value - Value
        result - the integer representation
        Throws:
        java.lang.IllegalArgumentException - if the value is negative or non-finite.