[jira] [Created] (RNG-178) Add stream support to JumpableUniformRandomProvider

["Alex Herbert (Jira)" <ji...@apache.org>]

Alex Herbert created RNG-178:
--------------------------------

             Summary: Add stream support to JumpableUniformRandomProvider
                 Key: RNG-178
                 URL: https://issues.apache.org/jira/browse/RNG-178
             Project: Commons RNG
          Issue Type: New Feature
          Components: client-api
    Affects Versions: 1.4
            Reporter: Alex Herbert
             Fix For: 1.5


The JumpableUniformRandomProvider can add default methods to allow a stream of generators to be created:
{code:java}
    default Stream<UniformRandomProvider> jumps() {
        return Stream.generate(this::jump).sequential();
    }

    default Stream<UniformRandomProvider> jumps(long streamSize) {
        return jumps().limit(streamSize);
    }
{code}
A similar method for the LongJumpableRandomGenerator can be provided.

Note: This method is found in the [JDK 17 JumpableGenerator|https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/random/RandomGenerator.JumpableGenerator.html] interface.

Other methods from that interface cannot be added as they have no default implementation. Note the JDK interface has separated the jump from the copy operation:
{code:java}
RandomGenerator.JumpableGenerator copy();
void jump();
default RandomGenerator copyAndJump();
double jumpDistance();
static RandomGenerator.JumpableGenerator of(String name);
{code}
Note the factory method is achieved in Commons RNG using:
{code:java}
JumpableUniformRandomProvider rng = (JumpableUniformRandomProvider)
    Arrays.stream(RandomSource.values())
          .filter(RandomSource::isJumpable)
          .findFirst()
          .get().create();
{code}
This involves an explicit cast in user code. It may be desirable to formalise this pattern by adding a Stream method to RandomSource:
{code:java}
public static Stream<RandomSource> stream();

JumpableUniformRandomProvider rng = (JumpableUniformRandomProvider)
    RandomSource.stream()
                .filter(RandomSource::isJumpable)
                .findFirst()
                .get().create();
{code}
Note that the jump distance is not provided by the Commons RNG API. It cannot be added to the interface due to binary compatibility constraints. It could be added to the RandomSource enum. This would allow filtering in a stream by minimum jump distance. This does however add properties to RandomSource for many instances where the property is not relevant (cluttering the API).

The JDK 17 equivalent feature for this is to create [Stream<RandomGeneratorFactory<RandomGenerator>> all()|https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/random/RandomGeneratorFactory.html#all()] factories and then filter on those. The [RandomGeneratorFactory|https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/random/RandomGeneratorFactory.html] instances are the equivalent of RandomSource instances as these have properties that can be used for filters. However it does not appear that the Jumpable generators can be filtered on their jump distance as this is not exposed by the factory for use in filtering the stream. The jump distance can be obtained after an instance of the generator has been created.



--
This message was sent by Atlassian Jira
(v8.20.7#820007)