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

Class SequenceInsertionSampler

java.lang.Object
org.cicirello.sequences.SequenceInsertionSampler
All Implemented Interfaces:
SequenceSampler
public final class SequenceInsertionSampler extends Object implements SequenceSampler
SequenceInsertionSampler generates random samples of array elements, without replacement.

The methods of this class implement the insertion sampling algorithm 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 of the sample methods is O(k2) and generates O(k) random numbers. Thus, it is a better choice than both SequenceReservoirSampler and SequencePoolSampler when k2 < n. Just like SequenceReservoirSampler, the SequenceInsertionSampler only requires O(1) extra space, while SequencePoolSampler requires O(n) extra space.

  • Constructor Summary

    Constructors
    Constructor
    Description
    SequenceInsertionSampler()
    Constructs a sampler with a default source of randomness.
    SequenceInsertionSampler(long seed)
    Constructs a sampler seeding the internal random number generator as specified.
    SequenceInsertionSampler(RandomGenerator r)
    Constructs a sampler wrapping a RandomGenerator used as the source of randomness.

  • Method Summary

    Modifier and Type
    Method
    Description
    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, RandomGenerator r)
    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, RandomGenerator r)
    Generates a random sample of k elements, without replacement, from a given source array.
    static char[]
    sample(char[] source, double p, RandomGenerator r)
    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, RandomGenerator r)
    Generates a random sample of k elements, without replacement, from a given source array.
    static double[]
    sample(double[] source, double p, RandomGenerator r)
    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, RandomGenerator r)
    Generates a random sample of k elements, without replacement, from a given source array.
    static float[]
    sample(float[] source, double p, RandomGenerator r)
    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, RandomGenerator r)
    Generates a random sample of k elements, without replacement, from a given source array.
    static int[]
    sample(int[] source, double p, RandomGenerator r)
    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, RandomGenerator r)
    Generates a random sample of k elements, without replacement, from a given source array.
    static long[]
    sample(long[] source, double p, RandomGenerator r)
    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, RandomGenerator r)
    Generates a random sample of k elements, without replacement, from a given source array.
    static short[]
    sample(short[] source, double p, RandomGenerator r)
    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, RandomGenerator r)
    Generates a random sample of k elements, without replacement, from a given source array.
    static char[]
    sample(String source, double p, RandomGenerator r)
    Generates a random sample, without replacement, from a given source String with a specified probability of an element's inclusion in the sample.
    static char[]
    sample(String source, int k, char[] target, RandomGenerator r)
    Generates a random sample of k chars, without replacement, from a given source String.
    static <T> T[]
    sample(T[] source, double p, RandomGenerator r)
    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, RandomGenerator r)
    Generates a random sample of k elements, without replacement, from a given source array.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • SequenceInsertionSampler

      public SequenceInsertionSampler(RandomGenerator r)
      Constructs a sampler wrapping a RandomGenerator used as the source of randomness.
      Parameters:
      r - The source of randomness.

    • SequenceInsertionSampler

      public SequenceInsertionSampler(long seed)
      Constructs a sampler seeding the internal random number generator as specified.
      Parameters:
      seed - The seed for the random number generator

    • SequenceInsertionSampler

      public SequenceInsertionSampler()
      Constructs a sampler with a default source of randomness.

  • Method Details

    • nextSample

      public 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.
      Specified by:
      nextSample in interface SequenceSampler
      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

    • nextSample

      public 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.
      Specified by:
      nextSample in interface SequenceSampler
      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

    • nextSample

      public 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.
      Specified by:
      nextSample in interface SequenceSampler
      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

    • nextSample

      public 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.
      Specified by:
      nextSample in interface SequenceSampler
      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

    • nextSample

      public 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.
      Specified by:
      nextSample in interface SequenceSampler
      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

    • nextSample

      public 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.
      Specified by:
      nextSample in interface SequenceSampler
      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

    • nextSample

      public 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.
      Specified by:
      nextSample in interface SequenceSampler
      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

    • nextSample

      public 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.
      Specified by:
      nextSample in interface SequenceSampler
      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.
      Throws:
      IllegalArgumentException - if k > source.length()
      NegativeArraySizeException - if k < 0

    • nextSample

      public <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.
      Specified by:
      nextSample in interface SequenceSampler
      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

    • nextSample

      public int[] nextSample(int[] source, double p)
      Description copied from interface: SequenceSampler
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
      Specified by:
      nextSample in interface SequenceSampler
      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

      public long[] nextSample(long[] source, double p)
      Description copied from interface: SequenceSampler
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
      Specified by:
      nextSample in interface SequenceSampler
      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

      public short[] nextSample(short[] source, double p)
      Description copied from interface: SequenceSampler
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
      Specified by:
      nextSample in interface SequenceSampler
      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

      public byte[] nextSample(byte[] source, double p)
      Description copied from interface: SequenceSampler
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
      Specified by:
      nextSample in interface SequenceSampler
      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

      public double[] nextSample(double[] source, double p)
      Description copied from interface: SequenceSampler
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
      Specified by:
      nextSample in interface SequenceSampler
      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

      public float[] nextSample(float[] source, double p)
      Description copied from interface: SequenceSampler
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
      Specified by:
      nextSample in interface SequenceSampler
      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

      public char[] nextSample(char[] source, double p)
      Description copied from interface: SequenceSampler
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
      Specified by:
      nextSample in interface SequenceSampler
      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

      public char[] nextSample(String source, double p)
      Description copied from interface: SequenceSampler
      Generates a random sample, without replacement, from a given source String with a specified probability of an element's inclusion in the sample.
      Specified by:
      nextSample in interface SequenceSampler
      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

      public <T> T[] nextSample(T[] source, double p)
      Description copied from interface: SequenceSampler
      Generates a random sample, without replacement, from a given source array with a specified probability of an element's inclusion in the sample.
      Specified by:
      nextSample in interface SequenceSampler
      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

      public static int[] sample(int[] source, double p, RandomGenerator r)
      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.
      r - The source of randomness.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • sample

      public static long[] sample(long[] source, double p, RandomGenerator r)
      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.
      r - The source of randomness.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • sample

      public static short[] sample(short[] source, double p, RandomGenerator r)
      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.
      r - The source of randomness.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • sample

      public static byte[] sample(byte[] source, double p, RandomGenerator r)
      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.
      r - The source of randomness.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • sample

      public static double[] sample(double[] source, double p, RandomGenerator r)
      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.
      r - The source of randomness.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • sample

      public static float[] sample(float[] source, double p, RandomGenerator r)
      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.
      r - The source of randomness.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • sample

      public static char[] sample(char[] source, double p, RandomGenerator r)
      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.
      r - The source of randomness.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • sample

      public static char[] sample(String source, double p, RandomGenerator r)
      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.
      r - The source of randomness.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • sample

      public static <T> T[] sample(T[] source, double p, RandomGenerator r)
      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.
      r - The source of randomness.
      Returns:
      An array containing the sample, whose sample size is simply the length of the array.

    • sample

      public static int[] sample(int[] source, int k, int[] target, RandomGenerator r)
      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.
      r - The source of randomness.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sample

      public static long[] sample(long[] source, int k, long[] target, RandomGenerator r)
      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.
      r - The source of randomness.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sample

      public static short[] sample(short[] source, int k, short[] target, RandomGenerator r)
      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.
      r - The source of randomness.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sample

      public static byte[] sample(byte[] source, int k, byte[] target, RandomGenerator r)
      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.
      r - The source of randomness.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sample

      public static char[] sample(char[] source, int k, char[] target, RandomGenerator r)
      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.
      r - The source of randomness.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sample

      public static char[] sample(String source, int k, char[] target, RandomGenerator r)
      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.
      Parameters:
      source - The source 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.
      r - The source of randomness.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length()
      NegativeArraySizeException - if k < 0

    • sample

      public static double[] sample(double[] source, int k, double[] target, RandomGenerator r)
      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.
      r - The source of randomness.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sample

      public static float[] sample(float[] source, int k, float[] target, RandomGenerator r)
      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.
      r - The source of randomness.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0

    • sample

      public static <T> T[] sample(T[] source, int k, T[] target, RandomGenerator r)
      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.
      r - The source of randomness.
      Returns:
      An array containing the random sample.
      Throws:
      IllegalArgumentException - if k > source.length
      NegativeArraySizeException - if k < 0