Merge pull request #299 from cicirello/reservoir-sampler

Implemented SequenceSampler interface in SequenceReservoirSampler

Author: cicirello

CHANGELOG.md

@@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased] - 2022-11-18
 
 ### Added
+* Added the SequenceSampler interface's methods to SequenceReservoirSampler.
 
 ### Changed
 * SequenceSampler converted from a utility class of static methods to an interface, retaining the existing static
@@ -15,6 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Deprecated
 
 ### Removed
+* SequenceSampler.sampleReservoir methods, previously deprecated in 4.3.0, replaced by the SequenceReservoirSampler class.
 
 ### Fixed
 

src/main/java/org/cicirello/sequences/AbstractSequenceSampler.java

@@ -34,7 +34,6 @@ abstract class AbstractSequenceSampler {
 
   /** prevent instantiation with a private constructor. */
   AbstractSequenceSampler() {}
-  ;
 
   static void validateK(int k, int sourceLength) {
     if (k > sourceLength) {

src/main/java/org/cicirello/sequences/SequenceReservoirSampler.java

@@ -26,8 +26,7 @@
 import org.cicirello.util.ArrayMinimumLengthEnforcer;
 
 /**
- * SequenceReservoirSampler is a class of utility methods for efficiently generating random samples
- * of array elements, without replacement.
+ * SequenceReservoirSampler generates random samples of array elements, without replacement.
  *
  * <p>The methods of this class use the reservoir sampling algorithm (Algorithm R) from J. Vitter's
  * 1985 article "Random Sampling with a Reservoir" from ACM Transactions on Mathematical Software.
@@ -38,10 +37,118 @@
  * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, <a
  *     href=https://www.cicirello.org/ target=_top>https://www.cicirello.org/</a>
  */
-public final class SequenceReservoirSampler extends AbstractSequenceSampler {
+public final class SequenceReservoirSampler extends AbstractSequenceSampler
+    implements SequenceSampler {
 
-  /** Class of static utility methods so prevent instantiation with a private constructor. */
-  private SequenceReservoirSampler() {}
+  private final RandomGenerator r;
+
+  /**
+   * Constructs a sampler wrapping a RandomGenerator used as the source of randomness.
+   *
+   * @param r The source of randomness.
+   */
+  public SequenceReservoirSampler(RandomGenerator r) {
+    this.r = r;
+  }
+
+  /**
+   * {@inheritDoc}
+   *
+   * @throws IllegalArgumentException if k &gt; source.length
+   * @throws NegativeArraySizeException if k &lt; 0
+   */
+  @Override
+  public int[] nextSample(int[] source, int k, int[] target) {
+    return sample(source, k, target, r);
+  }
+
+  /**
+   * {@inheritDoc}
+   *
+   * @throws IllegalArgumentException if k &gt; source.length
+   * @throws NegativeArraySizeException if k &lt; 0
+   */
+  @Override
+  public long[] nextSample(long[] source, int k, long[] target) {
+    return sample(source, k, target, r);
+  }
+
+  /**
+   * {@inheritDoc}
+   *
+   * @throws IllegalArgumentException if k &gt; source.length
+   * @throws NegativeArraySizeException if k &lt; 0
+   */
+  @Override
+  public short[] nextSample(short[] source, int k, short[] target) {
+    return sample(source, k, target, r);
+  }
+
+  /**
+   * {@inheritDoc}
+   *
+   * @throws IllegalArgumentException if k &gt; source.length
+   * @throws NegativeArraySizeException if k &lt; 0
+   */
+  @Override
+  public byte[] nextSample(byte[] source, int k, byte[] target) {
+    return sample(source, k, target, r);
+  }
+
+  /**
+   * {@inheritDoc}
+   *
+   * @throws IllegalArgumentException if k &gt; source.length
+   * @throws NegativeArraySizeException if k &lt; 0
+   */
+  @Override
+  public double[] nextSample(double[] source, int k, double[] target) {
+    return sample(source, k, target, r);
+  }
+
+  /**
+   * {@inheritDoc}
+   *
+   * @throws IllegalArgumentException if k &gt; source.length
+   * @throws NegativeArraySizeException if k &lt; 0
+   */
+  @Override
+  public float[] nextSample(float[] source, int k, float[] target) {
+    return sample(source, k, target, r);
+  }
+
+  /**
+   * {@inheritDoc}
+   *
+   * @throws IllegalArgumentException if k &gt; source.length
+   * @throws NegativeArraySizeException if k &lt; 0
+   */
+  @Override
+  public char[] nextSample(char[] source, int k, char[] target) {
+    return sample(source, k, target, r);
+  }
+
+  /**
+   * {@inheritDoc}
+   *
+   * @throws IllegalArgumentException if k &gt; source.length()
+   * @throws NegativeArraySizeException if k &lt; 0
+   */
+  @Override
+  public char[] nextSample(String source, int k, char[] target) {
+    return sample(source, k, target, r);
+  }
+
+  /**
+   * {@inheritDoc}
+   *
+   * @throws IllegalArgumentException if k &gt; source.length
+   * @throws NegativeArraySizeException if k &lt; 0
+   */
+  @Override
+  public <T> T[] nextSample(T[] source, int k, T[] target) {
+    return sample(source, k, target, r);
+  }
 
   /**
    * Generates a random sample of k elements, without replacement, from a given source array. All n