Module org.cicirello.jpt
Package org.cicirello.sequences

Interface SequenceSampler

All Known Implementing Classes:
SequenceCompositeSampler, SequenceInsertionSampler, SequencePoolSampler, SequenceReservoirSampler
public interface SequenceSampler
An implementation of the SequenceSampler interface is used for generating random samples of array elements, without replacement.

  • Method Summary

    Modifier and Type
    Method
    Description
    static SequenceSampler
    getDefault()
    Gets an instance of the default SequenceSampler with a default source of randomness.
    static SequenceSampler
    getDefault(long seed)
    Gets an instance of the default SequenceSampler with a seed specified for the internal random number generator.
    static SequenceSampler
    getDefault(RandomGenerator r)
    Gets an instance of the default SequenceSampler given a specified source of randomness.
    byte[]
    nextSample(byte[] source, double p)
    Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
    byte[]
    nextSample(byte[] source, int k, byte[] target)
    Generates a random sample of k elements, without replacement, from a given source array.
    char[]
    nextSample(char[] source, double p)
    Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
    char[]
    nextSample(char[] source, int k, char[] target)
    Generates a random sample of k elements, without replacement, from a given source array.
    double[]
    nextSample(double[] source, double p)
    Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
    double[]
    nextSample(double[] source, int k, double[] target)
    Generates a random sample of k elements, without replacement, from a given source array.
    float[]
    nextSample(float[] source, double p)
    Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
    float[]
    nextSample(float[] source, int k, float[] target)
    Generates a random sample of k elements, without replacement, from a given source array.
    int[]
    nextSample(int[] source, double p)
    Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
    int[]
    nextSample(int[] source, int k, int[] target)
    Generates a random sample of k elements, without replacement, from a given source array.
    long[]
    nextSample(long[] source, double p)
    Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
    long[]
    nextSample(long[] source, int k, long[] target)
    Generates a random sample of k elements, without replacement, from a given source array.
    short[]
    nextSample(short[] source, double p)
    Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
    short[]
    nextSample(short[] source, int k, short[] target)
    Generates a random sample of k elements, without replacement, from a given source array.
    char[]
    nextSample(String source, double p)
    Generates a random sample, without replacement, from a given source String with a specified probability of an element's inclusion in the sample.
    char[]
    nextSample(String source, int k, char[] target)
    Generates a random sample of k elements, without replacement, from a given source String.
    <T> T[]
    nextSample(T[] source, double p)
    Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
    <T> T[]
    nextSample(T[] source, int k, T[] target)
    Generates a random sample of k elements, without replacement, from a given source array.
    static byte[]
    sample(byte[] source, double p)
    Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
    static byte[]
    sample(byte[] source, int k, byte[] target)
    Generates a random sample of k elements, without replacement, from a given source array.
    static char[]
    sample(char[] source, double p)
    Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
    static char[]
    sample(char[] source, int k, char[] target)
    Generates a random sample of k elements, without replacement, from a given source array.
    static double[]
    sample(double[] source, double p)
    Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
    static double[]
    sample(double[] source, int k, double[] target)
    Generates a random sample of k elements, without replacement, from a given source array.
    static float[]
    sample(float[] source, double p)
    Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
    static float[]
    sample(float[] source, int k, float[] target)
    Generates a random sample of k elements, without replacement, from a given source array.
    static int[]
    sample(int[] source, double p)
    Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
    static int[]
    sample(int[] source, int k, int[] target)
    Generates a random sample of k elements, without replacement, from a given source array.
    static long[]
    sample(long[] source, double p)
    Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
    static long[]
    sample(long[] source, int k, long[] target)
    Generates a random sample of k elements, without replacement, from a given source array.
    static short[]
    sample(short[] source, double p)
    Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
    static short[]
    sample(short[] source, int k, short[] target)
    Generates a random sample of k elements, without replacement, from a given source array.
    static char[]
    sample(String source, double p)
    Generates a random sample, without replacement, from a given String with a specified probability of a character's inclusion in the sample.
    static char[]
    sample(String source, int k, char[] target)
    Generates a random sample of k chars, without replacement, from a given source String.
    static <T> T[]
    sample(T[] source, double p)
    Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
    static <T> T[]
    sample(T[] source, int k, T[] target)
    Generates a random sample of k elements, without replacement, from a given source array.

  • Method Details

    • nextSample

      int[] nextSample(int[] source, int k, int[] target)
      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.
      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      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.
      Returns:
      An array containing the random sample.

    • nextSample

      short[] nextSample(short[] source, int k, short[] target)
      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.
      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      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.
      Returns:
      An array containing the random sample.

    • nextSample

      long[] nextSample(long[] source, int k, long[] target)
      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.
      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      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.
      Returns:
      An array containing the random sample.

    • nextSample

      byte[] nextSample(byte[] source, int k, byte[] target)
      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.
      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      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.
      Returns:
      An array containing the random sample.

    • nextSample

      char[] nextSample(char[] source, int k, char[] target)
      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.
      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      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.
      Returns:
      An array containing the random sample.

    • nextSample

      char[] nextSample(String source, int k, char[] target)
      Generates a random sample of k elements, without replacement, from a given source String. All n choose k combinations are equally likely, where n is the length of the source String.
      Parameters:
      source - The source String to sample.
      k - The number of random samples (must be no greater than source.length).
      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.
      Returns:
      An array containing the random sample.

    • nextSample

      double[] nextSample(double[] source, int k, double[] target)
      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.
      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      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.
      Returns:
      An array containing the random sample.

    • nextSample

      float[] nextSample(float[] source, int k, float[] target)
      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.
      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      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.
      Returns:
      An array containing the random sample.

    • nextSample

      <T> T[] nextSample(T[] source, int k, T[] target)
      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.
      Type Parameters:
      T - The type of array elements.
      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      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.
      Returns:
      An array containing the random sample.

    • nextSample

      int[] nextSample(int[] source, double p)
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
      Parameters:
      source - The array from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length * p.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • nextSample

      long[] nextSample(long[] source, double p)
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
      Parameters:
      source - The array from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length * p.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • nextSample

      short[] nextSample(short[] source, double p)
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
      Parameters:
      source - The array from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length * p.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • nextSample

      byte[] nextSample(byte[] source, double p)
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
      Parameters:
      source - The array from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length * p.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • nextSample

      double[] nextSample(double[] source, double p)
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
      Parameters:
      source - The array from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length * p.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • nextSample

      float[] nextSample(float[] source, double p)
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
      Parameters:
      source - The array from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length * p.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • nextSample

      char[] nextSample(char[] source, double p)
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
      Parameters:
      source - The array from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length * p.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • nextSample

      char[] nextSample(String source, double p)
      Generates a random sample, without replacement, from a given source String with a specified probability of an element's inclusion in the sample.
      Parameters:
      source - The String from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length() * p.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • nextSample

      <T> T[] nextSample(T[] source, double p)
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
      Type Parameters:
      T - The type of array elements.
      Parameters:
      source - The array from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length * p.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • getDefault

      static SequenceSampler getDefault()
      Gets an instance of the default SequenceSampler with a default source of randomness. The default is currently SequenceCompositeSampler, but this may change in future releases without notice, so no assumptions should be made concerning the specific SequenceSampler returned by this method.
      Returns:
      an instance of the default SequenceSampler

    • getDefault

      static SequenceSampler getDefault(RandomGenerator r)
      Gets an instance of the default SequenceSampler given a specified source of randomness. The default is currently SequenceCompositeSampler, but this may change in future releases without notice, so no assumptions should be made concerning the specific SequenceSampler returned by this method.
      Parameters:
      r - The source of randomness.
      Returns:
      an instance of the default SequenceSampler

    • getDefault

      static SequenceSampler getDefault(long seed)
      Gets an instance of the default SequenceSampler with a seed specified for the internal random number generator. The default is currently SequenceCompositeSampler, but this may change in future releases without notice, so no assumptions should be made concerning the specific SequenceSampler returned by this method.
      Parameters:
      seed - The seed for the random number generator
      Returns:
      an instance of the default SequenceSampler

    • sample

      static byte[] sample(byte[] source, double p)
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.

      This method chooses among the SequencePoolSampler, SequenceReservoirSampler, and SequenceInsertionSampler classes based on the values of n and p.

      This approach combining reservoir sampling, pool sampling, and insertion sampling was described in: Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Parameters:
      source - The array from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length * p.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • sample

      static char[] sample(char[] source, double p)
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.

      This method chooses among the SequencePoolSampler, SequenceReservoirSampler, and SequenceInsertionSampler classes based on the values of n and p.

      This approach combining reservoir sampling, pool sampling, and insertion sampling was described in: Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Parameters:
      source - The array from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length * p.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • sample

      static double[] sample(double[] source, double p)
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.

      This method chooses among the SequencePoolSampler, SequenceReservoirSampler, and SequenceInsertionSampler classes based on the values of n and p.

      This approach combining reservoir sampling, pool sampling, and insertion sampling was described in: Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Parameters:
      source - The array from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length * p.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • sample

      static float[] sample(float[] source, double p)
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.

      This method chooses among the SequencePoolSampler, SequenceReservoirSampler, and SequenceInsertionSampler classes based on the values of n and p.

      This approach combining reservoir sampling, pool sampling, and insertion sampling was described in: Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Parameters:
      source - The array from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length * p.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • sample

      static int[] sample(int[] source, double p)
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.

      This method chooses among the SequencePoolSampler, SequenceReservoirSampler, and SequenceInsertionSampler classes based on the values of n and p.

      This approach combining reservoir sampling, pool sampling, and insertion sampling was described in: Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Parameters:
      source - The array from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length * p.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • sample

      static long[] sample(long[] source, double p)
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.

      This method chooses among the SequencePoolSampler, SequenceReservoirSampler, and SequenceInsertionSampler classes based on the values of n and p.

      This approach combining reservoir sampling, pool sampling, and insertion sampling was described in: Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Parameters:
      source - The array from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length * p.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • sample

      static short[] sample(short[] source, double p)
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.

      This method chooses among the SequencePoolSampler, SequenceReservoirSampler, and SequenceInsertionSampler classes based on the values of n and p.

      This approach combining reservoir sampling, pool sampling, and insertion sampling was described in: Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Parameters:
      source - The array from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length * p.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • sample

      static char[] sample(String source, double p)
      Generates a random sample, without replacement, from a given String with a specified probability of a character's inclusion in the sample.

      This method chooses among the SequencePoolSampler, SequenceReservoirSampler, and SequenceInsertionSampler classes based on the values of n and p.

      This approach combining reservoir sampling, pool sampling, and insertion sampling was described in: Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Parameters:
      source - The String from which to sample.
      p - The probability that a character is included in the sample. The expected sample size is source.length() * p.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • sample

      static <T> T[] sample(T[] source, double p)
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.

      This method chooses among the SequencePoolSampler, SequenceReservoirSampler, and SequenceInsertionSampler classes based on the values of n and p.

      This approach combining reservoir sampling, pool sampling, and insertion sampling was described in: Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Type Parameters:
      T - The type of array elements.
      Parameters:
      source - The array from which to sample.
      p - The probability that element is included in the sample. The expected sample size is source.length * p.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • sample

      static int[] sample(int[] source, int k, int[] target)
      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.

      This method chooses among the SequencePoolSampler, SequenceReservoirSampler, and SequenceInsertionSampler classes based on the values of n and k.

      This approach combining reservoir sampling, pool sampling, and insertion sampling was described in: Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      The runtime is O(min(n, k2)) and it generates O(min(k, n-k)) random numbers.

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      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.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sample

      static long[] sample(long[] source, int k, long[] target)
      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.

      This method chooses among the SequencePoolSampler, SequenceReservoirSampler, and SequenceInsertionSampler classes based on the values of n and k.

      This approach combining reservoir sampling, pool sampling, and insertion sampling was described in: Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      The runtime is O(min(n, k2)) and it generates O(min(k, n-k)) random numbers.

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      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.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sample

      static short[] sample(short[] source, int k, short[] target)
      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.

      This method chooses among the SequencePoolSampler, SequenceReservoirSampler, and SequenceInsertionSampler classes based on the values of n and k.

      This approach combining reservoir sampling, pool sampling, and insertion sampling was described in: Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      The runtime is O(min(n, k2)) and it generates O(min(k, n-k)) random numbers.

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      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.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sample

      static byte[] sample(byte[] source, int k, byte[] target)
      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.

      This method chooses among the SequencePoolSampler, SequenceReservoirSampler, and SequenceInsertionSampler classes based on the values of n and k.

      This approach combining reservoir sampling, pool sampling, and insertion sampling was described in: Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      The runtime is O(min(n, k2)) and it generates O(min(k, n-k)) random numbers.

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      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.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sample

      static char[] sample(char[] source, int k, char[] target)
      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.

      This method chooses among the SequencePoolSampler, SequenceReservoirSampler, and SequenceInsertionSampler classes based on the values of n and k.

      This approach combining reservoir sampling, pool sampling, and insertion sampling was described in: Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      The runtime is O(min(n, k2)) and it generates O(min(k, n-k)) random numbers.

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      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.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sample

      static char[] sample(String source, int k, char[] target)
      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.

      This method chooses among the SequencePoolSampler, SequenceReservoirSampler, and SequenceInsertionSampler classes based on the values of n and k.

      This approach combining reservoir sampling, pool sampling, and insertion sampling was described in: Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      The runtime is O(min(n, k2)) and it generates O(min(k, n-k)) random numbers.

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length()).
      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.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length()
      NegativeArraySizeException - if k < 0

    • sample

      static double[] sample(double[] source, int k, double[] target)
      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.

      This method chooses among the SequencePoolSampler, SequenceReservoirSampler, and SequenceInsertionSampler classes based on the values of n and k.

      This approach combining reservoir sampling, pool sampling, and insertion sampling was described in: Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      The runtime is O(min(n, k2)) and it generates O(min(k, n-k)) random numbers.

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      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.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sample

      static float[] sample(float[] source, int k, float[] target)
      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.

      This method chooses among the SequencePoolSampler, SequenceReservoirSampler, and SequenceInsertionSampler classes based on the values of n and k.

      This approach combining reservoir sampling, pool sampling, and insertion sampling was described in: Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      The runtime is O(min(n, k2)) and it generates O(min(k, n-k)) random numbers.

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      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.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sample

      static <T> T[] sample(T[] source, int k, T[] target)
      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.

      This method chooses among the SequencePoolSampler, SequenceReservoirSampler, and SequenceInsertionSampler classes based on the values of n and k.

      This approach combining reservoir sampling, pool sampling, and insertion sampling was described in: Vincent A. Cicirello. 2022. Cycle Mutation: Evolving Permutations via Cycle Induction, Applied Sciences, 12(11), Article 5506 (June 2022). doi:10.3390/app12115506

      The runtime is O(min(n, k2)) and it generates O(min(k, n-k)) random numbers.

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads.

      Type Parameters:
      T - The type of array elements.
      Parameters:
      source - The source array to sample.
      k - The number of random samples (must be no greater than source.length).
      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.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0