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)
