Package org.apache.commons.rng.core

Class BaseProvider

java.lang.Object
org.apache.commons.rng.core.BaseProvider
All Implemented Interfaces:
RestorableUniformRandomProvider, UniformRandomProvider
Direct Known Subclasses:
IntProvider, LongProvider
public abstract class BaseProvider
extends java.lang.Object
implements RestorableUniformRandomProvider
Base class with default implementation for common methods.

  • Constructor Summary

    Constructors 
    Constructor Description
    BaseProvider()  

  • Method Summary

    Modifier and Type Method Description
    protected void checkIndex​(int min, int max, int index)
    Checks whether index is in the range [min, max].
    protected void checkStateSize​(byte[] state, int expected)
    Deprecated.
    Method is used internally and should be made private in some future release.
    protected byte[] composeStateInternal​(byte[] state, byte[] parentState)
    Combine parent and subclass states.
    protected void fillState​(int[] state, int[] seed)
    Simple filling procedure.
    protected void fillState​(long[] state, long[] seed)
    Simple filling procedure.
    protected byte[] getStateInternal()
    Creates a snapshot of the RNG state.
    int nextInt​(int n)
    Generates an int value between 0 (inclusive) and the specified value (exclusive).
    long nextLong​(long n)
    Generates a long value between 0 (inclusive) and the specified value (exclusive).
    void restoreState​(RandomProviderState state)
    Restores the state of a generator.
    RandomProviderState saveState()
    Saves the state of a generator.
    protected void setStateInternal​(byte[] state)
    Resets the RNG to the given state.
    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.
    java.lang.String toString()

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface org.apache.commons.rng.UniformRandomProvider

    nextBoolean, nextBytes, nextBytes, nextDouble, nextFloat, nextInt, nextLong

  • Constructor Details

  • Method Details

    • nextInt

      public int nextInt​(int n)
      Generates an int value between 0 (inclusive) and the specified value (exclusive).
      Specified by:
      nextInt in interface UniformRandomProvider
      Parameters:
      n - Bound on the random number to be returned. Must be positive.
      Returns:
      a random int value between 0 (inclusive) and n (exclusive).

    • nextLong

      public long nextLong​(long n)
      Generates a long value between 0 (inclusive) and the specified value (exclusive).
      Specified by:
      nextLong in interface UniformRandomProvider
      Parameters:
      n - Bound on the random number to be returned. Must be positive.
      Returns:
      a random long value between 0 (inclusive) and n (exclusive).

    • saveState

      public RandomProviderState saveState()
      Saves the state of a generator.
      Specified by:
      saveState in interface RestorableUniformRandomProvider
      Returns:
      the current state of this instance. It is a value that can subsequently be passed to the restore method.

    • restoreState

      public void restoreState​(RandomProviderState state)
      Restores the state of a generator.
      Specified by:
      restoreState in interface RestorableUniformRandomProvider
      Parameters:
      state - State which this instance will be set to. This parameter would usually have been obtained by a call to saveState performed either on the same object as this one, or an object of the exact same class.

    • toString

      public java.lang.String toString()
      Overrides:
      toString in class java.lang.Object

    • 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:
      java.lang.IllegalStateException - if state.length < localStateLength.

    • getStateInternal

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

    • setStateInternal

      protected void setStateInternal​(byte[] state)
      Resets the RNG to the given state.
      Parameters:
      state - State (previously obtained by a call to getStateInternal()).
      Throws:
      java.lang.IllegalStateException - if the size of the given array is not consistent with the state defined by this class.
      See Also:
      checkStateSize(byte[],int)

    • 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:
      java.lang.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:
      java.lang.IndexOutOfBoundsException - if index is not within the [min, max] interval.