Merge pull request #300 from cicirello/pool-sampler

Implemented SequenceSampler interface in SequencePoolSampler

Author: cicirello

CHANGELOG.md

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

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

@@ -27,8 +27,7 @@
 import org.cicirello.util.ArrayMinimumLengthEnforcer;
 
 /**
- * SequencePoolSampler is a class of utility methods for efficiently generating random samples of
- * array elements, without replacement.
+ * SequencePoolSampler generates random samples of array elements, without replacement.
  *
  * <p>The methods of this class implement the algorithm SELECT of S. Goodman and S. Hedetniemi, as
  * described in: J Ernvall, O Nevalainen, "An Algorithm for Unbiased Random Sampling," The Computer
@@ -41,10 +40,117 @@
  * @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 SequencePoolSampler extends AbstractSequenceSampler {
+public final class SequencePoolSampler extends AbstractSequenceSampler implements SequenceSampler {
 
-  /** Class of static utility methods so prevent instantiation with a private constructor. */
-  private SequencePoolSampler() {}
+  private final RandomGenerator r;
+
+  /**
+   * Constructs a sampler wrapping a RandomGenerator used as the source of randomness.
+   *
+   * @param r The source of randomness.
+   */
+  public SequencePoolSampler(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