implement SequenceSampler interface

Author: cicirello

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

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

@@ -639,268 +639,6 @@ public static <T> T[] sample(T[] source, int k, T[] target) {
     return SequenceCompositeSampler.sample(source, k, target, ThreadLocalRandom.current());
   }
 
-  /**
-   * Generates a random sample of k elements, without replacement, from a given source array. All n
-   * choose k combinations are equally likely, where n is the length of the source array.
-   *
-   * <p>This implements the algorithm SELECT of S. Goodman and S. Hedetniemi, as described in: J
-   * Ernvall, O Nevalainen, "An Algorithm for Unbiased Random Sampling," The Computer Journal,
-   * 25(1):45-47, 1982.
-   *
-   * <p>The runtime is O(n) and it generates O(k) random numbers. Thus, it is a better choice than
-   * sampleReservoir when k &lt; n-k. However, this uses O(n) extra space, whereas the reservoir
-   * algorithm uses no extra space.
-   *
-   * <p>This method is safe to use with threads, as it uses ThreadLocalRandom as the underlying
-   * source of randomness.
-   *
-   * @deprecated This method is deprecated, and replaced by the {@link SequencePoolSampler} class.
-   * @param source The source array to sample.
-   * @param k The number of random samples (must be no greater than source.length).
-   * @param target An array to hold the result. If target is null or target.length is less than k,
-   *     then this method will construct a new array for the result.
-   * @return An array containing the random sample.
-   * @throws IllegalArgumentException if k &gt; source.length
-   * @throws NegativeArraySizeException if k &lt; 0
-   */
-  @Deprecated
-  public static int[] samplePool(int[] source, int k, int[] target) {
-    return SequencePoolSampler.sample(source, k, target, ThreadLocalRandom.current());
-  }
-
-  /**
-   * Generates a random sample of k elements, without replacement, from a given source array. All n
-   * choose k combinations are equally likely, where n is the length of the source array.
-   *
-   * <p>This implements the algorithm SELECT of S. Goodman and S. Hedetniemi, as described in: J
-   * Ernvall, O Nevalainen, "An Algorithm for Unbiased Random Sampling," The Computer Journal,
-   * 25(1):45-47, 1982.
-   *
-   * <p>The runtime is O(n) and it generates O(k) random numbers. Thus, it is a better choice than
-   * sampleReservoir when k &lt; n-k. However, this uses O(n) extra space, whereas the reservoir
-   * algorithm uses no extra space.
-   *
-   * <p>This method is safe to use with threads, as it uses ThreadLocalRandom as the underlying
-   * source of randomness.
-   *
-   * @deprecated This method is deprecated, and replaced by the {@link SequencePoolSampler} class.
-   * @param source The source array to sample.
-   * @param k The number of random samples (must be no greater than source.length).
-   * @param target An array to hold the result. If target is null or target.length is less than k,
-   *     then this method will construct a new array for the result.
-   * @return An array containing the random sample.
-   * @throws IllegalArgumentException if k &gt; source.length
-   * @throws NegativeArraySizeException if k &lt; 0
-   */
-  @Deprecated
-  public static long[] samplePool(long[] source, int k, long[] target) {
-    return SequencePoolSampler.sample(source, k, target, ThreadLocalRandom.current());
-  }
-
-  /**
-   * Generates a random sample of k elements, without replacement, from a given source array. All n
-   * choose k combinations are equally likely, where n is the length of the source array.
-   *
-   * <p>This implements the algorithm SELECT of S. Goodman and S. Hedetniemi, as described in: J
-   * Ernvall, O Nevalainen, "An Algorithm for Unbiased Random Sampling," The Computer Journal,
-   * 25(1):45-47, 1982.
-   *
-   * <p>The runtime is O(n) and it generates O(k) random numbers. Thus, it is a better choice than
-   * sampleReservoir when k &lt; n-k. However, this uses O(n) extra space, whereas the reservoir
-   * algorithm uses no extra space.
-   *
-   * <p>This method is safe to use with threads, as it uses ThreadLocalRandom as the underlying
-   * source of randomness.
-   *
-   * @deprecated This method is deprecated, and replaced by the {@link SequencePoolSampler} class.
-   * @param source The source array to sample.
-   * @param k The number of random samples (must be no greater than source.length).
-   * @param target An array to hold the result. If target is null or target.length is less than k,
-   *     then this method will construct a new array for the result.
-   * @return An array containing the random sample.
-   * @throws IllegalArgumentException if k &gt; source.length
-   * @throws NegativeArraySizeException if k &lt; 0
-   */
-  @Deprecated
-  public static short[] samplePool(short[] source, int k, short[] target) {
-    return SequencePoolSampler.sample(source, k, target, ThreadLocalRandom.current());
-  }
-
-  /**
-   * Generates a random sample of k elements, without replacement, from a given source array. All n
-   * choose k combinations are equally likely, where n is the length of the source array.
-   *
-   * <p>This implements the algorithm SELECT of S. Goodman and S. Hedetniemi, as described in: J
-   * Ernvall, O Nevalainen, "An Algorithm for Unbiased Random Sampling," The Computer Journal,
-   * 25(1):45-47, 1982.
-   *
-   * <p>The runtime is O(n) and it generates O(k) random numbers. Thus, it is a better choice than
-   * sampleReservoir when k &lt; n-k. However, this uses O(n) extra space, whereas the reservoir
-   * algorithm uses no extra space.
-   *
-   * <p>This method is safe to use with threads, as it uses ThreadLocalRandom as the underlying
-   * source of randomness.
-   *
-   * @deprecated This method is deprecated, and replaced by the {@link SequencePoolSampler} class.
-   * @param source The source array to sample.
-   * @param k The number of random samples (must be no greater than source.length).
-   * @param target An array to hold the result. If target is null or target.length is less than k,
-   *     then this method will construct a new array for the result.
-   * @return An array containing the random sample.
-   * @throws IllegalArgumentException if k &gt; source.length
-   * @throws NegativeArraySizeException if k &lt; 0
-   */
-  @Deprecated
-  public static byte[] samplePool(byte[] source, int k, byte[] target) {
-    return SequencePoolSampler.sample(source, k, target, ThreadLocalRandom.current());
-  }
-
-  /**
-   * Generates a random sample of k elements, without replacement, from a given source array. All n
-   * choose k combinations are equally likely, where n is the length of the source array.
-   *
-   * <p>This implements the algorithm SELECT of S. Goodman and S. Hedetniemi, as described in: J
-   * Ernvall, O Nevalainen, "An Algorithm for Unbiased Random Sampling," The Computer Journal,
-   * 25(1):45-47, 1982.
-   *
-   * <p>The runtime is O(n) and it generates O(k) random numbers. Thus, it is a better choice than
-   * sampleReservoir when k &lt; n-k. However, this uses O(n) extra space, whereas the reservoir
-   * algorithm uses no extra space.
-   *
-   * <p>This method is safe to use with threads, as it uses ThreadLocalRandom as the underlying
-   * source of randomness.
-   *
-   * @deprecated This method is deprecated, and replaced by the {@link SequencePoolSampler} class.
-   * @param source The source array to sample.
-   * @param k The number of random samples (must be no greater than source.length).
-   * @param target An array to hold the result. If target is null or target.length is less than k,
-   *     then this method will construct a new array for the result.
-   * @return An array containing the random sample.
-   * @throws IllegalArgumentException if k &gt; source.length
-   * @throws NegativeArraySizeException if k &lt; 0
-   */
-  @Deprecated
-  public static char[] samplePool(char[] source, int k, char[] target) {
-    return SequencePoolSampler.sample(source, k, target, ThreadLocalRandom.current());
-  }
-
-  /**
-   * Generates a random sample of k chars, without replacement, from a given source String. All n
-   * choose k combinations are equally likely, where n is the length of the source String.
-   *
-   * <p>This implements the algorithm SELECT of S. Goodman and S. Hedetniemi, as described in: J
-   * Ernvall, O Nevalainen, "An Algorithm for Unbiased Random Sampling," The Computer Journal,
-   * 25(1):45-47, 1982.
-   *
-   * <p>The runtime is O(n) and it generates O(k) random numbers. Thus, it is a better choice than
-   * sampleReservoir when k &lt; n-k. However, this uses O(n) extra space, whereas the reservoir
-   * algorithm uses no extra space.
-   *
-   * <p>This method is safe to use with threads, as it uses ThreadLocalRandom as the underlying
-   * source of randomness.
-   *
-   * @deprecated This method is deprecated, and replaced by the {@link SequencePoolSampler} class.
-   * @param source The source to sample.
-   * @param k The number of random samples (must be no greater than source.length()).
-   * @param target An array to hold the result. If target is null or target.length is less than k,
-   *     then this method will construct a new array for the result.
-   * @return An array containing the random sample.
-   * @throws IllegalArgumentException if k &gt; source.length()
-   * @throws NegativeArraySizeException if k &lt; 0
-   */
-  @Deprecated
-  public static char[] samplePool(String source, int k, char[] target) {
-    return SequencePoolSampler.sample(source, k, target, ThreadLocalRandom.current());
-  }
-
-  /**
-   * Generates a random sample of k elements, without replacement, from a given source array. All n
-   * choose k combinations are equally likely, where n is the length of the source array.
-   *
-   * <p>This implements the algorithm SELECT of S. Goodman and S. Hedetniemi, as described in: J
-   * Ernvall, O Nevalainen, "An Algorithm for Unbiased Random Sampling," The Computer Journal,
-   * 25(1):45-47, 1982.
-   *
-   * <p>The runtime is O(n) and it generates O(k) random numbers. Thus, it is a better choice than
-   * sampleReservoir when k &lt; n-k. However, this uses O(n) extra space, whereas the reservoir
-   * algorithm uses no extra space.
-   *
-   * <p>This method is safe to use with threads, as it uses ThreadLocalRandom as the underlying
-   * source of randomness.
-   *
-   * @deprecated This method is deprecated, and replaced by the {@link SequencePoolSampler} class.
-   * @param source The source array to sample.
-   * @param k The number of random samples (must be no greater than source.length).
-   * @param target An array to hold the result. If target is null or target.length is less than k,
-   *     then this method will construct a new array for the result.
-   * @return An array containing the random sample.
-   * @throws IllegalArgumentException if k &gt; source.length
-   * @throws NegativeArraySizeException if k &lt; 0
-   */
-  @Deprecated
-  public static double[] samplePool(double[] source, int k, double[] target) {
-    return SequencePoolSampler.sample(source, k, target, ThreadLocalRandom.current());
-  }
-
-  /**
-   * Generates a random sample of k elements, without replacement, from a given source array. All n
-   * choose k combinations are equally likely, where n is the length of the source array.
-   *
-   * <p>This implements the algorithm SELECT of S. Goodman and S. Hedetniemi, as described in: J
-   * Ernvall, O Nevalainen, "An Algorithm for Unbiased Random Sampling," The Computer Journal,
-   * 25(1):45-47, 1982.
-   *
-   * <p>The runtime is O(n) and it generates O(k) random numbers. Thus, it is a better choice than
-   * sampleReservoir when k &lt; n-k. However, this uses O(n) extra space, whereas the reservoir
-   * algorithm uses no extra space.
-   *
-   * <p>This method is safe to use with threads, as it uses ThreadLocalRandom as the underlying
-   * source of randomness.
-   *
-   * @deprecated This method is deprecated, and replaced by the {@link SequencePoolSampler} class.
-   * @param source The source array to sample.
-   * @param k The number of random samples (must be no greater than source.length).
-   * @param target An array to hold the result. If target is null or target.length is less than k,
-   *     then this method will construct a new array for the result.
-   * @return An array containing the random sample.
-   * @throws IllegalArgumentException if k &gt; source.length
-   * @throws NegativeArraySizeException if k &lt; 0
-   */
-  @Deprecated
-  public static float[] samplePool(float[] source, int k, float[] target) {
-    return SequencePoolSampler.sample(source, k, target, ThreadLocalRandom.current());
-  }
-
-  /**
-   * Generates a random sample of k elements, without replacement, from a given source array. All n
-   * choose k combinations are equally likely, where n is the length of the source array.
-   *
-   * <p>This implements the algorithm SELECT of S. Goodman and S. Hedetniemi, as described in: J
-   * Ernvall, O Nevalainen, "An Algorithm for Unbiased Random Sampling," The Computer Journal,
-   * 25(1):45-47, 1982.
-   *
-   * <p>The runtime is O(n) and it generates O(k) random numbers. Thus, it is a better choice than
-   * sampleReservoir when k &lt; n-k. However, this uses O(n) extra space, whereas the reservoir
-   * algorithm uses no extra space.
-   *
-   * <p>This method is safe to use with threads, as it uses ThreadLocalRandom as the underlying
-   * source of randomness.
-   *
-   * @deprecated This method is deprecated, and replaced by the {@link SequencePoolSampler} class.
-   * @param source The source array to sample.
-   * @param k The number of random samples (must be no greater than source.length).
-   * @param target An array to hold the result. If target is null or target.length is less than k,
-   *     then this method will construct a new array for the result.
-   * @param <T> The type of array elements.
-   * @return An array containing the random sample.
-   * @throws IllegalArgumentException if k &gt; source.length
-   * @throws NegativeArraySizeException if k &lt; 0
-   */
-  @Deprecated
-  public static <T> T[] samplePool(T[] source, int k, T[] target) {
-    return SequencePoolSampler.sample(source, k, target, ThreadLocalRandom.current());
-  }
-
   /**
    * Generates a random sample of k elements, without replacement, from a given source array. All n
    * choose k combinations are equally likely, where n is the length of the source array.