Package org.apache.commons.rng.core

Class BaseProvider

    • Constructor Detail

    • Method Detail

      • composeStateInternal

        protected byte[] composeStateInternal​(byte[] state,
                                      byte[] parentState)
        Combine parent and subclass states. This method must be called by all subclasses in order to ensure that state can be restored in case some of it is stored higher up in the class hierarchy. I.e. the body of the overridden getStateInternal(), will end with a statement like the following: 
          
    return composeStateInternal(state,
                                super.getStateInternal());
        where state is the state needed and defined by the class where the method is overridden.
        Parameters:
        state - State of the calling class.
        parentState - State of the calling class' parent.
        Returns:
        the combined state. Bytes that belong to the local state will be stored at the beginning of the resulting array.

      • splitStateInternal

        protected byte[][] splitStateInternal​(byte[] state,
                                      int localStateLength)
        Splits the given state into a part to be consumed by the caller in order to restore its local state, while the reminder is passed to the parent class. I.e. the body of the overridden setStateInternal(byte[]), will contain statements like the following: 
          
    final byte[][] s = splitState(state, localStateLength);
    // Use "s[0]" to recover the local state.
    super.setStateInternal(s[1]);
        where state is the combined state of the calling class and of all its parents.
        Parameters:
        state - State. The local state must be stored at the beginning of the array.
        localStateLength - Number of elements that will be consumed by the locally defined state.
        Returns:
        the local state (in slot 0) and the parent state (in slot 1).
        Throws:
        IllegalStateException - if state.length < localStateLength.

      • getStateInternal

        protected byte[] getStateInternal()
        Creates a snapshot of the RNG state.
        Returns:
        the internal state.

      • fillState

        protected void fillState​(int[] state,
                         int[] seed)
        Simple filling procedure. It will
        1. fill the beginning of state by copying min(seed.length, state.length) elements from seed,
        2. set all remaining elements of state with non-zero values (even if seed.length < state.length).
        Parameters:
        state - State. Must be allocated.
        seed - Seed. Cannot be null.

      • fillState

        protected void fillState​(long[] state,
                         long[] seed)
        Simple filling procedure. It will
        1. fill the beginning of state by copying min(seed.length, state.length) elements from seed,
        2. set all remaining elements of state with non-zero values (even if seed.length < state.length).
        Parameters:
        state - State. Must be allocated.
        seed - Seed. Cannot be null.

      • checkStateSize

        @Deprecated
protected void checkStateSize​(byte[] state,
                              int expected)
        Deprecated.
        Method is used internally and should be made private in some future release.
        Checks that the state has the expected size.
        Parameters:
        state - State.
        expected - Expected length of state array.
        Throws:
        IllegalStateException - if state.length < expected.

      • checkIndex

        protected void checkIndex​(int min,
                          int max,
                          int index)
        Checks whether index is in the range [min, max].
        Parameters:
        min - Lower bound.
        max - Upper bound.
        index - Value that must lie within the [min, max] interval.
        Throws:
        IndexOutOfBoundsException - if index is not within the [min, max] interval.

      • extendSeed

        protected static long[] extendSeed​(long[] seed,
                                   int length)
        Extend the seed to the specified minimum length. If the seed is equal or greater than the minimum length, return the same seed unchanged. Otherwise:
        1. Create a new array of the specified length
        2. Copy all elements of the seed into the array
        3. Fill the remaining values. The additional values will have at most one occurrence of zero. If the original seed is all zero, the first extended value will be non-zero.

        This method can be used in constructors that must pass their seed to the super class to avoid a duplication of seed expansion to the minimum length required by the super class and the class: 

         public RNG extends AnotherRNG {
     public RNG(long[] seed) {
         super(seed = extendSeed(seed, SEED_SIZE));
         // Use seed for additional state ...
     }
 }

        Note using the state filling procedure provided in fillState(long[], long[]) is not possible as it is an instance method. Calling a seed extension routine must use a static method.

        This method functions as if the seed has been extended using a SplitMix64 generator seeded with seed[0], or zero if the input seed length is zero. 

         if (seed.length < length) {
     final long[] s = Arrays.copyOf(seed, length);
     final SplitMix64 rng = new SplitMix64(s[0]);
     for (int i = seed.length; i < length; i++) {
         s[i] = rng.nextLong();
     }
     return s;
 }
        Parameters:
        seed - Input seed
        length - The minimum length
        Returns:
        the seed
        Since:
        1.5

      • extendSeed

        protected static int[] extendSeed​(int[] seed,
                                  int length)
        Extend the seed to the specified minimum length. If the seed is equal or greater than the minimum length, return the same seed unchanged. Otherwise:
        1. Create a new array of the specified length
        2. Copy all elements of the seed into the array
        3. Fill the remaining values. The additional values will have at most one occurrence of zero. If the original seed is all zero, the first extended value will be non-zero.

        This method can be used in constructors that must pass their seed to the super class to avoid a duplication of seed expansion to the minimum length required by the super class and the class: 

         public RNG extends AnotherRNG {
     public RNG(int[] seed) {
         super(seed = extendSeed(seed, SEED_SIZE));
         // Use seed for additional state ...
     }
 }

        Note using the state filling procedure provided in fillState(int[], int[]) is not possible as it is an instance method. Calling a seed extension routine must use a static method.

        This method functions as if the seed has been extended using a SplitMix64-style 32-bit generator seeded with seed[0], or zero if the input seed length is zero. The generator uses the 32-bit mixing function from MurmurHash3.

        Parameters:
        seed - Input seed
        length - The minimum length
        Returns:
        the seed
        Since:
        1.5