Module org.cicirello.rho_mu
Package org.cicirello.math.rand

Class RandomIndexer

java.lang.Object
org.cicirello.math.rand.RandomIndexer
public final class RandomIndexer extends Object
RandomIndexer is a class of utility methods related to efficiently generating random indexes, and combination of indexes, into arrays. The methods of this class neither directly operate, nor depend, on arrays, and can thus be used wherever you need random integer values. The name of the class is derived from the motivating case, the case of efficiently generating random indexes into an array.

  • Method Summary

    Modifier and Type
    Method
    Description
    static boolean[]
    arrayMask(int n)
    Generates an "array mask" of a specified length, where an "array mask" is an array of boolean values of the same length as another array.
    static boolean[]
    arrayMask(int n, double p)
    Generates an "array mask" of a specified length, where an "array mask" is an array of boolean values of the same length as another array.
    static boolean[]
    arrayMask(int n, double p, RandomGenerator gen)
    Generates an "array mask" of a specified length, where an "array mask" is an array of boolean values of the same length as another array.
    static boolean[]
    arrayMask(int n, int k)
    Generates an "array mask" of a specified length and specified number of true values, where an "array mask" is an array of boolean values of the same length as another array.
    static boolean[]
    arrayMask(int n, int k, RandomGenerator gen)
    Generates an "array mask" of a specified length and specified number of true values, where an "array mask" is an array of boolean values of the same length as another array.
    static boolean[]
    arrayMask(int n, RandomGenerator gen)
    Generates an "array mask" of a specified length, where an "array mask" is an array of boolean values of the same length as another array.
    static int
    nextBiasedInt(int bound)
    Generates a random integer in the interval: [0, bound).
    static int
    nextBiasedInt(int origin, int bound)
    Generates a random integer in the interval: [origin, bound).
    static int
    nextBiasedInt(int origin, int bound, RandomGenerator gen)
    Generates a random integer in the interval: [origin, bound).
    static int
    nextBiasedInt(int bound, RandomGenerator gen)
    Generates a random integer in the interval: [0, bound).
    static int
    nextInt(int bound)
    Generates a random integer uniformly distributed in the interval: [0, bound).
    static int
    nextInt(int origin, int bound)
    Generates a random integer uniformly distributed in the interval: [origin, bound).
    static int
    nextInt(int origin, int bound, RandomGenerator gen)
    Generates a random integer uniformly distributed in the interval: [origin, bound).
    static int
    nextInt(int bound, RandomGenerator gen)
    Generates a random integer uniformly distributed in the interval: [0, bound).
    static IndexPair
    nextIntPair(int n)
    Generates a random sample of 2 integers, without replacement, from the set of integers in the interval [0, n).
    static int[]
    nextIntPair(int n, int[] result)
    Generates a random sample of 2 integers, without replacement, from the set of integers in the interval [0, n).
    static int[]
    nextIntPair(int n, int[] result, RandomGenerator gen)
    Generates a random sample of 2 integers, without replacement, from the set of integers in the interval [0, n).
    static IndexPair
    nextIntPair(int n, RandomGenerator gen)
    Generates a random sample of 2 integers, without replacement, from the set of integers in the interval [0, n).
    static IndexTriple
    nextIntTriple(int n)
    Generates a random sample of 3 integers, without replacement, from the set of integers in the interval [0, n).
    static int[]
    nextIntTriple(int n, int[] result)
    Generates a random sample of 3 integers, without replacement, from the set of integers in the interval [0, n).
    static int[]
    nextIntTriple(int n, int[] result, RandomGenerator gen)
    Generates a random sample of 3 integers, without replacement, from the set of integers in the interval [0, n).
    static IndexTriple
    nextIntTriple(int n, RandomGenerator gen)
    Generates a random sample of 3 integers, without replacement, from the set of integers in the interval [0, n).
    static IndexPair
    nextSortedIntPair(int n)
    Generates a random sample of 2 integers (i, j) without replacement, from the set of integers in the interval [0, n).
    static int[]
    nextSortedIntPair(int n, int[] result)
    Generates a random sample of 2 integers, without replacement, from the set of integers in the interval [0, n).
    static int[]
    nextSortedIntPair(int n, int[] result, RandomGenerator gen)
    Generates a random sample of 2 integers, without replacement, from the set of integers in the interval [0, n).
    static IndexPair
    nextSortedIntPair(int n, RandomGenerator gen)
    Generates a random sample of 2 integers (i, j) without replacement, from the set of integers in the interval [0, n).
    static IndexTriple
    nextSortedIntTriple(int n)
    Generates a random sample of 3 integers, without replacement, from the set of integers in the interval [0, n).
    static int[]
    nextSortedIntTriple(int n, int[] result)
    Generates a random sample of 3 integers, without replacement, from the set of integers in the interval [0, n).
    static int[]
    nextSortedIntTriple(int n, int[] result, RandomGenerator gen)
    Generates a random sample of 3 integers, without replacement, from the set of integers in the interval [0, n).
    static IndexTriple
    nextSortedIntTriple(int n, RandomGenerator gen)
    Generates a random sample of 3 integers, without replacement, from the set of integers in the interval [0, n).
    static IndexPair
    nextSortedWindowedIntPair(int n, int window)
    Generates a random sample of 2 integers (i, j) without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window, and sorted such that i is less than j.
    static int[]
    nextSortedWindowedIntPair(int n, int window, int[] result)
    Generates a random sample of 2 integers (i, j) without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window, and sorted such that i is less than j.
    static int[]
    nextSortedWindowedIntPair(int n, int window, int[] result, RandomGenerator gen)
    Generates a random sample of 2 integers (i, j) without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window, and sorted such that i is less than j.
    static IndexPair
    nextSortedWindowedIntPair(int n, int window, RandomGenerator gen)
    Generates a random sample of 2 integers (i, j) without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window, and sorted such that i is less than j.
    static IndexTriple
    nextSortedWindowedIntTriple(int n, int window)
    Generates a random sample of 3 integers, i, j, k without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window, and |i-k| ≤ window, and |k-j| ≤ window.
    static int[]
    nextSortedWindowedIntTriple(int n, int window, int[] result)
    Generates a random sample of 3 integers, i, j, k without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window, and |i-k| ≤ window, and |k-j| ≤ window.
    static int[]
    nextSortedWindowedIntTriple(int n, int window, int[] result, RandomGenerator gen)
    Generates a random sample of 3 integers, i, j, k without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window, and |i-k| ≤ window, and |k-j| ≤ window.
    static IndexTriple
    nextSortedWindowedIntTriple(int n, int window, RandomGenerator gen)
    Generates a random sample of 3 integers, i, j, k without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window, and |i-k| ≤ window, and |k-j| ≤ window.
    static IndexPair
    nextWindowedIntPair(int n, int window)
    Generates a random sample of 2 integers, i, j, without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window.
    static int[]
    nextWindowedIntPair(int n, int window, int[] result)
    Generates a random sample of 2 integers, i, j, without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window.
    static int[]
    nextWindowedIntPair(int n, int window, int[] result, RandomGenerator gen)
    Generates a random sample of 2 integers, i, j, without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window.
    static IndexPair
    nextWindowedIntPair(int n, int window, RandomGenerator gen)
    Generates a random sample of 2 integers, i, j, without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window.
    static IndexTriple
    nextWindowedIntTriple(int n, int window)
    Generates a random sample of 3 integers, i, j, k without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window, and |i-k| ≤ window, and |k-j| ≤ window.
    static int[]
    nextWindowedIntTriple(int n, int window, int[] result)
    Generates a random sample of 3 integers, i, j, k without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window, and |i-k| ≤ window, and |k-j| ≤ window.
    static int[]
    nextWindowedIntTriple(int n, int window, int[] result, RandomGenerator gen)
    Generates a random sample of 3 integers, i, j, k without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window, and |i-k| ≤ window, and |k-j| ≤ window.
    static IndexTriple
    nextWindowedIntTriple(int n, int window, RandomGenerator gen)
    Generates a random sample of 3 integers, i, j, k without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window, and |i-k| ≤ window, and |k-j| ≤ window.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • arrayMask

      public static boolean[] arrayMask(int n)
      Generates an "array mask" of a specified length, where an "array mask" is an array of boolean values of the same length as another array. Each position in the result is equally likely true or false.

      Runtime: O(n).

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

      Parameters:
      n - The length of the array mask.
      Returns:
      An array of n randomly generated boolean values.

    • arrayMask

      public static boolean[] arrayMask(int n, RandomGenerator gen)
      Generates an "array mask" of a specified length, where an "array mask" is an array of boolean values of the same length as another array. Each position in the result is equally likely true or false.

      Runtime: O(n).

      Parameters:
      n - The length of the array mask.
      gen - The source of randomness.
      Returns:
      An array of n randomly generated boolean values.

    • arrayMask

      public static boolean[] arrayMask(int n, int k)
      Generates an "array mask" of a specified length and specified number of true values, where an "array mask" is an array of boolean values of the same length as another array.

      Runtime: O(min(n, k2)), and it uses 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:
      n - The length of the array mask.
      k - The desired number of true values, which must be no greater than n.
      Returns:
      An array of n boolean values, exactly k of which are equal to true.

    • arrayMask

      public static boolean[] arrayMask(int n, int k, RandomGenerator gen)
      Generates an "array mask" of a specified length and specified number of true values, where an "array mask" is an array of boolean values of the same length as another array.

      Runtime: O(min(n, k2)), and it uses O(min(k, n-k)) random numbers.

      Parameters:
      n - The length of the array mask.
      k - The desired number of true values, which must be no greater than n.
      gen - The source of randomness.
      Returns:
      An array of n boolean values, exactly k of which are equal to true.

    • arrayMask

      public static boolean[] arrayMask(int n, double p)
      Generates an "array mask" of a specified length, where an "array mask" is an array of boolean values of the same length as another array.

      Runtime: O(n), and it uses O(n) random doubles.

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

      Parameters:
      n - The length of the array mask.
      p - The probability that an element of the result is true.
      Returns:
      An array of n boolean values, such that each element is true with probability p.

    • arrayMask

      public static boolean[] arrayMask(int n, double p, RandomGenerator gen)
      Generates an "array mask" of a specified length, where an "array mask" is an array of boolean values of the same length as another array.

      Runtime: O(n), and it uses O(n) random doubles.

      Parameters:
      n - The length of the array mask.
      p - The probability that an element of the result is true.
      gen - The source of randomness.
      Returns:
      An array of n boolean values, such that each element is true with probability p.

    • nextBiasedInt

      public static int nextBiasedInt(int bound)
      Generates a random integer in the interval: [0, bound).

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads. However, it does not use ThreadLocalRandom.nextInt(int bound) method. Instead, our nextBiasedInt(int bound) method computes a random int in the target interval via a multiplication and a shift, rather than the more common mod. This method does not correct for bias via rejection sampling, and thus some values in the interval [0, bound) may be more likely than others. There is no bias for bound values that are powers of 2. Otherwise, the lower the value of bound, the less bias; and the higher the value of bound, the more bias. If your bound is relatively low, and if your application does not require strict uniformity, then this method is significantly faster than any approach that corrects for bias. We started with the algorithm proposed in the article: Daniel Lemire, "Fast Random Integer Generation in an Interval," ACM Transactions on Modeling and Computer Simulation, 29(1), 2019. But we removed from it the rejection sampling portion.

      Parameters:
      bound - Upper bound, exclusive, on range of random integers (must be positive).
      Returns:
      a random integer between 0 (inclusive) and bound (exclusive).
      Throws:
      IllegalArgumentException - if the bound is not positive

    • nextBiasedInt

      public static int nextBiasedInt(int origin, int bound)
      Generates a random integer in the interval: [origin, bound).

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads. However, it does not use ThreadLocalRandom.nextInt(int origin, int bound) method. Instead, our nextBiasedInt(int origin, int bound) method computes a random int in the target interval via a multiplication and a shift, rather than the more common mod. This method does not correct for bias via rejection sampling, and thus some values in the interval [origin, bound) may be more likely than others. There is no bias if the width of the interval is a power of 2. Otherwise, the smaller the interval, the less bias; and the larger the interval, the more bias. If your interval is relatively small, and if your application does not require strict uniformity, then this method is significantly faster than any approach that corrects for bias. We started with the algorithm proposed in the article: Daniel Lemire, "Fast Random Integer Generation in an Interval," ACM Transactions on Modeling and Computer Simulation, 29(1), 2019. But we removed from it the rejection sampling portion.

      Parameters:
      origin - Lower bound, inclusive, on range of random integers.
      bound - Upper bound, exclusive, on range of random integers (must be greater than origin).
      Returns:
      a random integer between origin (inclusive) and bound (exclusive).
      Throws:
      IllegalArgumentException - if the bound is not greater than the origin

    • nextBiasedInt

      public static int nextBiasedInt(int origin, int bound, RandomGenerator gen)
      Generates a random integer in the interval: [origin, bound).

      This method does not use RandomGenerator.nextInt(int origin, int bound) method. Instead, our nextBiasedInt(int origin, int bound) method computes a random int in the target interval via a multiplication and a shift, rather than the more common mod. This method does not correct for bias via rejection sampling, and thus some values in the interval [origin, bound) may be more likely than others. There is no bias if the width of the interval is a power of 2. Otherwise, the smaller the interval, the less bias; and the larger the interval, the more bias. If your interval is relatively small, and if your application does not require strict uniformity, then this method is significantly faster than any approach that corrects for bias. We started with the algorithm proposed in the article: Daniel Lemire, "Fast Random Integer Generation in an Interval," ACM Transactions on Modeling and Computer Simulation, 29(1), 2019. But we removed from it the rejection sampling portion.

      Parameters:
      origin - Lower bound, inclusive, on range of random integers.
      bound - Upper bound, exclusive, on range of random integers (must be greater than origin).
      gen - A source of randomness.
      Returns:
      a random integer between origin (inclusive) and bound (exclusive).
      Throws:
      IllegalArgumentException - if the bound is not greater than the origin

    • nextBiasedInt

      public static int nextBiasedInt(int bound, RandomGenerator gen)
      Generates a random integer in the interval: [0, bound).

      This method does not use RandomGenerator.nextInt(int bound) method. Instead, our nextBiasedInt(int bound) method computes a random int in the target interval via a multiplication and a shift, rather than the more common mod. This method does not correct for bias via rejection sampling, and thus some values in the interval [0, bound) may be more likely than others. There is no bias for bound values that are powers of 2. Otherwise, the lower the value of bound, the less bias; and the higher the value of bound, the more bias. If your bound is relatively low, and if your application does not require strict uniformity, then this method is significantly faster than any approach that corrects for bias. We started with the algorithm proposed in the article: Daniel Lemire, "Fast Random Integer Generation in an Interval," ACM Transactions on Modeling and Computer Simulation, 29(1), 2019. But we removed from it the rejection sampling portion.

      Parameters:
      bound - Upper bound, exclusive, on range of random integers (must be positive).
      gen - A source of randomness.
      Returns:
      a random integer between 0 (inclusive) and bound (exclusive).
      Throws:
      IllegalArgumentException - if the bound is not positive

    • nextInt

      public static int nextInt(int bound)
      Generates a random integer uniformly distributed in the interval: [0, bound).

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads. However, it does not use ThreadLocalRandom.nextInt(int bound) method. Instead, our nextInt(int bound) method is an implementation of the algorithm proposed in the article: Daniel Lemire, "Fast Random Integer Generation in an Interval," ACM Transactions on Modeling and Computer Simulation, 29(1), 2019.

      This method is significantly faster than ThreadLocalRandom.nextInt(int bound).

      Parameters:
      bound - Upper bound, exclusive, on range of random integers (must be positive).
      Returns:
      a random integer between 0 (inclusive) and bound (exclusive).
      Throws:
      IllegalArgumentException - if the bound is not positive

    • nextInt

      public static int nextInt(int origin, int bound)
      Generates a random integer uniformly distributed in the interval: [origin, bound).

      This method uses ThreadLocalRandom as the pseudorandom number generator, and is thus safe, and efficient (i.e., non-blocking), for use with threads. However, it does not use ThreadLocalRandom.nextInt(int origin, int bound) method. Instead, our nextInt(int origin, int bound) method is an implementation of the algorithm proposed in the article: Daniel Lemire, "Fast Random Integer Generation in an Interval," ACM Transactions on Modeling and Computer Simulation, 29(1), 2019.

      This method is significantly faster than ThreadLocalRandom.nextInt(int bound).

      Parameters:
      origin - Lower bound, inclusive, on range of random integers.
      bound - Upper bound, exclusive, on range of random integers (must be greater than origin).
      Returns:
      a random integer between origin (inclusive) and bound (exclusive).
      Throws:
      IllegalArgumentException - if the bound is not greater than origin

    • nextInt

      public static int nextInt(int origin, int bound, RandomGenerator gen)
      Generates a random integer uniformly distributed in the interval: [origin, bound).

      This method uses a RandomGenerator passed as a parameter as the pseudorandom number generator. However, it does not use RandomGenerator.nextInt(int origin, int bound) method. Instead, our nextInt(int origin, int bound) method is an implementation of the algorithm proposed in the article: Daniel Lemire, "Fast Random Integer Generation in an Interval," ACM Transactions on Modeling and Computer Simulation, 29(1), 2019.

      Parameters:
      origin - Lower bound, inclusive, on range of random integers.
      bound - Upper bound, exclusive, on range of random integers (must be greater than origin).
      gen - A source of randomness.
      Returns:
      a random integer between origin (inclusive) and bound (exclusive).
      Throws:
      IllegalArgumentException - if the bound is not greater than origin

    • nextInt

      public static int nextInt(int bound, RandomGenerator gen)
      Generates a random integer uniformly distributed in the interval: [0, bound).

      This method uses a RandomGenerator passed as a parameter as the pseudorandom number generator. However, it does not use RandomGenerator.nextInt(int bound) method. Instead, our nextInt(int bound) method is an implementation of the algorithm proposed in the article: Daniel Lemire, "Fast Random Integer Generation in an Interval," ACM Transactions on Modeling and Computer Simulation, 29(1), 2019.

      Parameters:
      bound - Upper bound, exclusive, on range of random integers (must be positive).
      gen - A source of randomness.
      Returns:
      a random integer between 0 (inclusive) and bound (exclusive).
      Throws:
      IllegalArgumentException - if the bound is not positive

    • nextIntPair

      public static int[] nextIntPair(int n, int[] result)
      Generates a random sample of 2 integers, without replacement, from the set of integers in the interval [0, n). All n choose 2 combinations are equally likely.

      The runtime of this method is O(1), and it uses an algorithm described in:

      Vincent A. Cicirello. 2024. Algorithms for Generating Small Random Samples. Software: Practice and Experience, September 2024. doi:10.1002/spe.3379 [PDF]

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

      Parameters:
      n - The number of integers to choose from.
      result - An array to hold the pair that is generated. If result is null or if result.length is less than 2, then this method will construct an array for the result.
      Returns:
      An array containing the pair of randomly chosen integers from the interval [0, n).
      Throws:
      IllegalArgumentException - if n < 2.

    • nextIntPair

      public static int[] nextIntPair(int n, int[] result, RandomGenerator gen)
      Generates a random sample of 2 integers, without replacement, from the set of integers in the interval [0, n). All n choose 2 combinations are equally likely.

      The runtime of this method is O(1), and it uses an algorithm described in:

      Vincent A. Cicirello. 2024. Algorithms for Generating Small Random Samples. Software: Practice and Experience, September 2024. doi:10.1002/spe.3379 [PDF]

      Parameters:
      n - The number of integers to choose from.
      result - An array to hold the pair that is generated. If result is null or if result.length is less than 2, then this method will construct an array for the result.
      gen - Source of randomness.
      Returns:
      An array containing the pair of randomly chosen integers from the interval [0, n).
      Throws:
      IllegalArgumentException - if n < 2.

    • nextIntPair

      public static IndexPair nextIntPair(int n)
      Generates a random sample of 2 integers, without replacement, from the set of integers in the interval [0, n). All n choose 2 combinations are equally likely.

      The runtime of this method is O(1), and it uses an algorithm described in:

      Vincent A. Cicirello. 2024. Algorithms for Generating Small Random Samples. Software: Practice and Experience, September 2024. doi:10.1002/spe.3379 [PDF]

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

      Parameters:
      n - The number of integers to choose from.
      Returns:
      A pair of randomly chosen integers from the interval [0, n).
      Throws:
      IllegalArgumentException - if n < 2.

    • nextIntPair

      public static IndexPair nextIntPair(int n, RandomGenerator gen)
      Generates a random sample of 2 integers, without replacement, from the set of integers in the interval [0, n). All n choose 2 combinations are equally likely.

      The runtime of this method is O(1), and it uses an algorithm described in:

      Vincent A. Cicirello. 2024. Algorithms for Generating Small Random Samples. Software: Practice and Experience, September 2024. doi:10.1002/spe.3379 [PDF]

      Parameters:
      n - The number of integers to choose from.
      gen - Source of randomness.
      Returns:
      A pair of randomly chosen integers from the interval [0, n).
      Throws:
      IllegalArgumentException - if n < 2.

    • nextIntTriple

      public static int[] nextIntTriple(int n, int[] result)
      Generates a random sample of 3 integers, without replacement, from the set of integers in the interval [0, n). All n choose 3 combinations are equally likely.

      The runtime of this method is O(1), and it uses an algorithm described in:

      Vincent A. Cicirello. 2024. Algorithms for Generating Small Random Samples. Software: Practice and Experience, September 2024. doi:10.1002/spe.3379 [PDF]

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

      Parameters:
      n - The number of integers to choose from.
      result - An array to hold the pair that is generated. If result is null or if result.length is less than 3, then this method will construct an array for the result.
      Returns:
      An array containing the triple of randomly chosen integers from the interval [0, n).
      Throws:
      IllegalArgumentException - if n < 3.

    • nextIntTriple

      public static int[] nextIntTriple(int n, int[] result, RandomGenerator gen)
      Generates a random sample of 3 integers, without replacement, from the set of integers in the interval [0, n). All n choose 3 combinations are equally likely.

      The runtime of this method is O(1), and it uses an algorithm described in:

      Vincent A. Cicirello. 2024. Algorithms for Generating Small Random Samples. Software: Practice and Experience, September 2024. doi:10.1002/spe.3379 [PDF]

      Parameters:
      n - The number of integers to choose from.
      result - An array to hold the pair that is generated. If result is null or if result.length is less than 3, then this method will construct an array for the result.
      gen - Source of randomness.
      Returns:
      An array containing the triple of randomly chosen integers from the interval [0, n).
      Throws:
      IllegalArgumentException - if n < 3.

    • nextIntTriple

      public static IndexTriple nextIntTriple(int n)
      Generates a random sample of 3 integers, without replacement, from the set of integers in the interval [0, n). All n choose 3 combinations are equally likely.

      The runtime of this method is O(1), and it uses an algorithm described in:

      Vincent A. Cicirello. 2024. Algorithms for Generating Small Random Samples. Software: Practice and Experience, September 2024. doi:10.1002/spe.3379 [PDF]

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

      Parameters:
      n - The number of integers to choose from.
      Returns:
      A triple of randomly chosen integers from the interval [0, n).
      Throws:
      IllegalArgumentException - if n < 3.

    • nextIntTriple

      public static IndexTriple nextIntTriple(int n, RandomGenerator gen)
      Generates a random sample of 3 integers, without replacement, from the set of integers in the interval [0, n). All n choose 3 combinations are equally likely.

      The runtime of this method is O(1), and it uses an algorithm described in:

      Vincent A. Cicirello. 2024. Algorithms for Generating Small Random Samples. Software: Practice and Experience, September 2024. doi:10.1002/spe.3379 [PDF]

      Parameters:
      n - The number of integers to choose from.
      gen - Source of randomness.
      Returns:
      A triple of randomly chosen integers from the interval [0, n).
      Throws:
      IllegalArgumentException - if n < 3.

    • nextSortedIntPair

      public static int[] nextSortedIntPair(int n, int[] result)
      Generates a random sample of 2 integers, without replacement, from the set of integers in the interval [0, n). The integers in the pair are sorted with minimum first followed by maximum. All n choose 2 combinations are equally likely.

      The runtime of this method is O(1), and it uses an algorithm described in:

      Vincent A. Cicirello. 2024. Algorithms for Generating Small Random Samples. Software: Practice and Experience, September 2024. doi:10.1002/spe.3379 [PDF]

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

      Parameters:
      n - The number of integers to choose from.
      result - An array to hold the pair that is generated. If result is null or if result.length is less than 2, then this method will construct an array for the result.
      Returns:
      An array containing the pair of randomly chosen integers from the interval [0, n).
      Throws:
      IllegalArgumentException - if n < 2.

    • nextSortedIntPair

      public static int[] nextSortedIntPair(int n, int[] result, RandomGenerator gen)
      Generates a random sample of 2 integers, without replacement, from the set of integers in the interval [0, n). The integers in the pair are sorted with minimum first followed by maximum. All n choose 2 combinations are equally likely.

      The runtime of this method is O(1), and it uses an algorithm described in:

      Vincent A. Cicirello. 2024. Algorithms for Generating Small Random Samples. Software: Practice and Experience, September 2024. doi:10.1002/spe.3379 [PDF]

      Parameters:
      n - The number of integers to choose from.
      result - An array to hold the pair that is generated. If result is null or if result.length is less than 2, then this method will construct an array for the result.
      gen - Source of randomness.
      Returns:
      An array containing the pair of randomly chosen integers from the interval [0, n).
      Throws:
      IllegalArgumentException - if n < 2.

    • nextSortedIntPair

      public static IndexPair nextSortedIntPair(int n)
      Generates a random sample of 2 integers (i, j) without replacement, from the set of integers in the interval [0, n). The integers in the pair are sorted with i equal to the minimum and j equal to the maximum. All n choose 2 combinations are equally likely.

      The runtime of this method is O(1), and it uses an algorithm described in:

      Vincent A. Cicirello. 2024. Algorithms for Generating Small Random Samples. Software: Practice and Experience, September 2024. doi:10.1002/spe.3379 [PDF]

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

      Parameters:
      n - The number of integers to choose from.
      Returns:
      A pair of randomly chosen integers from the interval [0, n).
      Throws:
      IllegalArgumentException - if n < 2.

    • nextSortedIntPair

      public static IndexPair nextSortedIntPair(int n, RandomGenerator gen)
      Generates a random sample of 2 integers (i, j) without replacement, from the set of integers in the interval [0, n). The integers in the pair are sorted with i equal to the minimum and j equal to the maximum. All n choose 2 combinations are equally likely.

      The runtime of this method is O(1), and it uses an algorithm described in:

      Vincent A. Cicirello. 2024. Algorithms for Generating Small Random Samples. Software: Practice and Experience, September 2024. doi:10.1002/spe.3379 [PDF]

      Parameters:
      n - The number of integers to choose from.
      gen - Source of randomness.
      Returns:
      A pair of randomly chosen integers from the interval [0, n).
      Throws:
      IllegalArgumentException - if n < 2.

    • nextSortedIntTriple

      public static int[] nextSortedIntTriple(int n, int[] result)
      Generates a random sample of 3 integers, without replacement, from the set of integers in the interval [0, n). All n choose 3 combinations are equally likely. The result is sorted in increasing order.

      The runtime of this method is O(1), and it uses an algorithm described in:

      Vincent A. Cicirello. 2024. Algorithms for Generating Small Random Samples. Software: Practice and Experience, September 2024. doi:10.1002/spe.3379 [PDF]

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

      Parameters:
      n - The number of integers to choose from.
      result - An array to hold the pair that is generated. If result is null or if result.length is less than 3, then this method will construct an array for the result.
      Returns:
      An array containing the triple of randomly chosen integers from the interval [0, n).
      Throws:
      IllegalArgumentException - if n < 3.

    • nextSortedIntTriple

      public static int[] nextSortedIntTriple(int n, int[] result, RandomGenerator gen)
      Generates a random sample of 3 integers, without replacement, from the set of integers in the interval [0, n). All n choose 3 combinations are equally likely. The result is sorted in increasing order.

      The runtime of this method is O(1), and it uses an algorithm described in:

      Vincent A. Cicirello. 2024. Algorithms for Generating Small Random Samples. Software: Practice and Experience, September 2024. doi:10.1002/spe.3379 [PDF]

      Parameters:
      n - The number of integers to choose from.
      result - An array to hold the pair that is generated. If result is null or if result.length is less than 3, then this method will construct an array for the result.
      gen - The source of randomness.
      Returns:
      An array containing the triple of randomly chosen integers from the interval [0, n).
      Throws:
      IllegalArgumentException - if n < 3.

    • nextSortedIntTriple

      public static IndexTriple nextSortedIntTriple(int n)
      Generates a random sample of 3 integers, without replacement, from the set of integers in the interval [0, n). All n choose 3 combinations are equally likely. The result is sorted in increasing order.

      The runtime of this method is O(1), and it uses an algorithm described in:

      Vincent A. Cicirello. 2024. Algorithms for Generating Small Random Samples. Software: Practice and Experience, September 2024. doi:10.1002/spe.3379 [PDF]

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

      Parameters:
      n - The number of integers to choose from.
      Returns:
      A triple of randomly chosen integers from the interval [0, n).
      Throws:
      IllegalArgumentException - if n < 3.

    • nextSortedIntTriple

      public static IndexTriple nextSortedIntTriple(int n, RandomGenerator gen)
      Generates a random sample of 3 integers, without replacement, from the set of integers in the interval [0, n). All n choose 3 combinations are equally likely. The result is sorted in increasing order.

      The runtime of this method is O(1), and it uses an algorithm described in:

      Vincent A. Cicirello. 2024. Algorithms for Generating Small Random Samples. Software: Practice and Experience, September 2024. doi:10.1002/spe.3379 [PDF]

      Parameters:
      n - The number of integers to choose from.
      gen - The source of randomness.
      Returns:
      A triple of randomly chosen integers from the interval [0, n).
      Throws:
      IllegalArgumentException - if n < 3.

    • nextSortedWindowedIntPair

      public static int[] nextSortedWindowedIntPair(int n, int window, int[] result)
      Generates a random sample of 2 integers (i, j) without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window, and sorted such that i is less than j. All pairs that satisfy the window constraint are equally likely.

      The runtime is O(1).

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

      Parameters:
      n - The number of integers to choose from.
      window - The maximum difference between the integers of the pair.
      result - An array to hold the pair that is generated. If result is null or if result.length is less than 2, then this method will construct an array for the result.
      Returns:
      An array containing the pair of randomly chosen integers, i, j, from the interval [0, n), such that |i-j| ≤ window.
      Throws:
      IllegalArgumentException - if window < 1 or n < 2.

    • nextSortedWindowedIntPair

      public static int[] nextSortedWindowedIntPair(int n, int window, int[] result, RandomGenerator gen)
      Generates a random sample of 2 integers (i, j) without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window, and sorted such that i is less than j. All pairs that satisfy the window constraint are equally likely.

      The runtime is O(1).

      Parameters:
      n - The number of integers to choose from.
      window - The maximum difference between the integers of the pair.
      result - An array to hold the pair that is generated. If result is null or if result.length is less than 2, then this method will construct an array for the result.
      gen - Source of randomness.
      Returns:
      An array containing the pair of randomly chosen integers, i, j, from the interval [0, n), such that |i-j| ≤ window.
      Throws:
      IllegalArgumentException - if window < 1 or n < 2.

    • nextSortedWindowedIntPair

      public static IndexPair nextSortedWindowedIntPair(int n, int window)
      Generates a random sample of 2 integers (i, j) without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window, and sorted such that i is less than j. All pairs that satisfy the window constraint are equally likely.

      The runtime is O(1).

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

      Parameters:
      n - The number of integers to choose from.
      window - The maximum difference between the integers of the pair.
      Returns:
      A pair of randomly chosen integers, i, j, from the interval [0, n), such that |i-j| ≤ window.
      Throws:
      IllegalArgumentException - if window < 1 or n < 2.

    • nextSortedWindowedIntPair

      public static IndexPair nextSortedWindowedIntPair(int n, int window, RandomGenerator gen)
      Generates a random sample of 2 integers (i, j) without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window, and sorted such that i is less than j. All pairs that satisfy the window constraint are equally likely.

      The runtime is O(1).

      Parameters:
      n - The number of integers to choose from.
      window - The maximum difference between the integers of the pair.
      gen - Source of randomness.
      Returns:
      A pair of randomly chosen integers, i, j, from the interval [0, n), such that |i-j| ≤ window.
      Throws:
      IllegalArgumentException - if window < 1 or n < 2.

    • nextSortedWindowedIntTriple

      public static int[] nextSortedWindowedIntTriple(int n, int window, int[] result)
      Generates a random sample of 3 integers, i, j, k without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window, and |i-k| ≤ window, and |k-j| ≤ window. All triples that satisfy the window constraint are equally likely. The result is sorted in increasing order.

      The runtime is O(1).

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

      Parameters:
      n - The number of integers to choose from.
      window - The maximum difference between the integers of the triple.
      result - An array to hold the pair that is generated. If result is null or if result.length is less than 3, then this method will construct an array for the result.
      Returns:
      An array containing the triple of randomly chosen integers, i, j, k from the interval [0, n), such that |i-j| ≤ window, and |i-k| ≤ window, and |k-j| ≤ window.
      Throws:
      IllegalArgumentException - if window < 2 or n < 3.

    • nextSortedWindowedIntTriple

      public static int[] nextSortedWindowedIntTriple(int n, int window, int[] result, RandomGenerator gen)
      Generates a random sample of 3 integers, i, j, k without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window, and |i-k| ≤ window, and |k-j| ≤ window. All triples that satisfy the window constraint are equally likely. The result is sorted in increasing order.

      The runtime is O(1).

      Parameters:
      n - The number of integers to choose from.
      window - The maximum difference between the integers of the triple.
      result - An array to hold the pair that is generated. If result is null or if result.length is less than 3, then this method will construct an array for the result.
      gen - The source of randomness.
      Returns:
      An array containing the triple of randomly chosen integers, i, j, k from the interval [0, n), such that |i-j| ≤ window, and |i-k| ≤ window, and |k-j| ≤ window.
      Throws:
      IllegalArgumentException - if window < 2 or n < 3.

    • nextSortedWindowedIntTriple

      public static IndexTriple nextSortedWindowedIntTriple(int n, int window)
      Generates a random sample of 3 integers, i, j, k without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window, and |i-k| ≤ window, and |k-j| ≤ window. All triples that satisfy the window constraint are equally likely. The result is sorted in increasing order.

      The runtime is O(1).

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

      Parameters:
      n - The number of integers to choose from.
      window - The maximum difference between the integers of the triple.
      Returns:
      A triple of randomly chosen integers, i, j, k from the interval [0, n), such that |i-j| ≤ window, and |i-k| ≤ window, and |k-j| ≤ window.
      Throws:
      IllegalArgumentException - if window < 2 or n < 3.

    • nextSortedWindowedIntTriple

      public static IndexTriple nextSortedWindowedIntTriple(int n, int window, RandomGenerator gen)
      Generates a random sample of 3 integers, i, j, k without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window, and |i-k| ≤ window, and |k-j| ≤ window. All triples that satisfy the window constraint are equally likely. The result is sorted in increasing order.

      The runtime is O(1).

      Parameters:
      n - The number of integers to choose from.
      window - The maximum difference between the integers of the triple.
      gen - The source of randomness.
      Returns:
      A triple of randomly chosen integers, i, j, k from the interval [0, n), such that |i-j| ≤ window, and |i-k| ≤ window, and |k-j| ≤ window.
      Throws:
      IllegalArgumentException - if window < 2 or n < 3.

    • nextWindowedIntPair

      public static int[] nextWindowedIntPair(int n, int window, int[] result)
      Generates a random sample of 2 integers, i, j, without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window. All pairs that satisfy the window constraint are equally likely.

      The runtime is O(1).

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

      Parameters:
      n - The number of integers to choose from.
      window - The maximum difference between the integers of the pair.
      result - An array to hold the pair that is generated. If result is null or if result.length is less than 2, then this method will construct an array for the result.
      Returns:
      An array containing the pair of randomly chosen integers, i, j, from the interval [0, n), such that |i-j| ≤ window.
      Throws:
      IllegalArgumentException - if window < 1 or n < 2.

    • nextWindowedIntPair

      public static int[] nextWindowedIntPair(int n, int window, int[] result, RandomGenerator gen)
      Generates a random sample of 2 integers, i, j, without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window. All pairs that satisfy the window constraint are equally likely.

      The runtime is O(1).

      Parameters:
      n - The number of integers to choose from.
      window - The maximum difference between the integers of the pair.
      result - An array to hold the pair that is generated. If result is null or if result.length is less than 2, then this method will construct an array for the result.
      gen - Source of randomness.
      Returns:
      An array containing the pair of randomly chosen integers, i, j, from the interval [0, n), such that |i-j| ≤ window.
      Throws:
      IllegalArgumentException - if window < 1 or n < 2.

    • nextWindowedIntPair

      public static IndexPair nextWindowedIntPair(int n, int window)
      Generates a random sample of 2 integers, i, j, without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window. All pairs that satisfy the window constraint are equally likely.

      The runtime is O(1).

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

      Parameters:
      n - The number of integers to choose from.
      window - The maximum difference between the integers of the pair.
      Returns:
      A pair of randomly chosen integers, i, j, from the interval [0, n), such that |i-j| ≤ window.
      Throws:
      IllegalArgumentException - if window < 1 or n < 2.

    • nextWindowedIntPair

      public static IndexPair nextWindowedIntPair(int n, int window, RandomGenerator gen)
      Generates a random sample of 2 integers, i, j, without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window. All pairs that satisfy the window constraint are equally likely.

      The runtime is O(1).

      Parameters:
      n - The number of integers to choose from.
      window - The maximum difference between the integers of the pair.
      gen - Source of randomness.
      Returns:
      A pair of randomly chosen integers, i, j, from the interval [0, n), such that |i-j| ≤ window.
      Throws:
      IllegalArgumentException - if window < 1 or n < 2.

    • nextWindowedIntTriple

      public static int[] nextWindowedIntTriple(int n, int window, int[] result)
      Generates a random sample of 3 integers, i, j, k without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window, and |i-k| ≤ window, and |k-j| ≤ window. All triples that satisfy the window constraint are equally likely.

      The runtime is O(1).

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

      Parameters:
      n - The number of integers to choose from.
      window - The maximum difference between the integers of the triple.
      result - An array to hold the pair that is generated. If result is null or if result.length is less than 3, then this method will construct an array for the result.
      Returns:
      An array containing the triple of randomly chosen integers, i, j, k from the interval [0, n), such that |i-j| ≤ window, and |i-k| ≤ window, and |k-j| ≤ window.
      Throws:
      IllegalArgumentException - if window < 2 or n < 3.

    • nextWindowedIntTriple

      public static int[] nextWindowedIntTriple(int n, int window, int[] result, RandomGenerator gen)
      Generates a random sample of 3 integers, i, j, k without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window, and |i-k| ≤ window, and |k-j| ≤ window. All triples that satisfy the window constraint are equally likely.

      The runtime is O(1).

      Parameters:
      n - The number of integers to choose from.
      window - The maximum difference between the integers of the triple.
      result - An array to hold the pair that is generated. If result is null or if result.length is less than 3, then this method will construct an array for the result.
      gen - The source of randomness.
      Returns:
      An array containing the triple of randomly chosen integers, i, j, k from the interval [0, n), such that |i-j| ≤ window, and |i-k| ≤ window, and |k-j| ≤ window.
      Throws:
      IllegalArgumentException - if window < 2 or n < 3.

    • nextWindowedIntTriple

      public static IndexTriple nextWindowedIntTriple(int n, int window)
      Generates a random sample of 3 integers, i, j, k without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window, and |i-k| ≤ window, and |k-j| ≤ window. All triples that satisfy the window constraint are equally likely.

      The runtime is O(1).

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

      Parameters:
      n - The number of integers to choose from.
      window - The maximum difference between the integers of the triple.
      Returns:
      A triple of randomly chosen integers, i, j, k from the interval [0, n), such that |i-j| ≤ window, and |i-k| ≤ window, and |k-j| ≤ window.
      Throws:
      IllegalArgumentException - if window < 2 or n < 3.

    • nextWindowedIntTriple

      public static IndexTriple nextWindowedIntTriple(int n, int window, RandomGenerator gen)
      Generates a random sample of 3 integers, i, j, k without replacement, from the set of integers in the interval [0, n), such that |i-j| ≤ window, and |i-k| ≤ window, and |k-j| ≤ window. All triples that satisfy the window constraint are equally likely.

      The runtime is O(1).

      Parameters:
      n - The number of integers to choose from.
      window - The maximum difference between the integers of the triple.
      gen - The source of randomness.
      Returns:
      A triple of randomly chosen integers, i, j, k from the interval [0, n), such that |i-j| ≤ window, and |i-k| ≤ window, and |k-j| ≤ window.
      Throws:
      IllegalArgumentException - if window < 2 or n < 3.