Added generation of random pairs of distinct integers sorted with sma…

…ller first (#298)

* reordered methods alphabetically

* added nextSortedIntPair

* test cases for streams of sorted pairs

* Update CHANGELOG.md

CHANGELOG.md

@@ -17,10 +17,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   * Versions of nextWindowedIntPair using the new IndexPair class
   * Versions of nextWindowedIntTriple using the new IndexTriple class
 * Methods in the RandomIndexer and EnhancedRandomGenerator classes for generating additional combinations of distinct integers (both array-based versions and versions using IndexPair and IndexTriple), including:
+  * nextSortedIntPair: a variation of nextIntPair whose result is in sorted order.
   * nextSortedIntTriple: a variation of nextIntTriple whose result is in sorted order.
   * nextSortedWindowedIntTriple: a variation of nextWindowedIntTriple whose result is in sorted order.
 * Methods in the EnhancedRandomGenerator class for generating streams of combinations of distinct integers as streams of IndexPair or IndexTriple objects, including streams of the following:
   * Streams of random pairs of distinct integers (method pairs)
+  * Streams of random pairs of distinct sorted integers (method sortedPairs)
   * Streams of random pairs of distinct integers, separated by at most a specified window (method windowedPairs)
   * Streams of random triples of distinct integers (method triples)
   * Streams of random triples of distinct sorted integers (method sortedTriples)

src/main/java/org/cicirello/math/rand/EnhancedRandomGenerator.java

@@ -512,6 +512,38 @@ public final IndexTriple nextIntTriple(int n) {
     return RandomIndexer.nextIntTriple(n, generator);
   }
 
+  /**
+   * Generates a random sample of 2 integers, without replacement, from the set of integers in the
+   * interval [0, n). The result is sorted with the minimum first followed by the maximum. All n
+   * choose 2 combinations are equally likely. <b>Enhanced Functionality.</b>
+   *
+   * <p>The runtime is O(1).
+   *
+   * @param n The number of integers to choose from.
+   * @param 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.
+   * @return An array containing the pair of randomly chosen integers from the interval [0, n).
+   * @throws IllegalArgumentException if n &lt; 2.
+   */
+  public final int[] nextSortedIntPair(int n, int[] result) {
+    return RandomIndexer.nextSortedIntPair(n, result, generator);
+  }
+
+  /**
+   * Generates a random sample of 2 integers (i, j) without replacement, from the set of integers in
+   * the interval [0, n). The pair is sorted such that i is the minimum and j is the maximum. All n
+   * choose 2 combinations are equally likely. <b>Enhanced Functionality.</b>
+   *
+   * <p>The runtime is O(1).
+   *
+   * @param n The number of integers to choose from.
+   * @return A pair of randomly chosen integers from the interval [0, n).
+   * @throws IllegalArgumentException if n &lt; 2.
+   */
+  public final IndexPair nextSortedIntPair(int n) {
+    return RandomIndexer.nextSortedIntPair(n, generator);
+  }
+
   /**
    * 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
@@ -795,6 +827,33 @@ public final int[] sampleReservoir(int n, int k, int[] result) {
     return RandomSampler.sampleReservoir(n, k, result, generator);
   }
 
+  /**
+   * Returns an effectively unlimited stream of pseudorandom pairs of int values, without
+   * replacement, from the interval [0, n). Each pair is sorted such that i is the minimum and j is
+   * the maximum of the pair. <b>Enhanced Functionality.</b>
+   *
+   * @param n bound on random values, exclusive.
+   * @return an effectively unlimited stream of pseudorandom pairs of int values, without
+   *     replacement, from the interval [0, n).
+   */
+  public final Stream<IndexPair> sortedPairs(int n) {
+    return Stream.generate(() -> nextSortedIntPair(n)).sequential();
+  }
+
+  /**
+   * Returns a stream of pseudorandom pairs of int values, without replacement, from the interval
+   * [0, n). Each pair is sorted such that i is the minimum and j is the maximum of the pair.
+   * <b>Enhanced Functionality.</b>
+   *
+   * @param streamSize The number of values in the stream.
+   * @param n bound on random values, exclusive.
+   * @return a stream of pseudorandom pairs of int values, without replacement, from the interval
+   *     [0, n).
+   */
+  public final Stream<IndexPair> sortedPairs(long streamSize, int n) {
+    return Stream.generate(() -> nextSortedIntPair(n)).sequential().limit(streamSize);
+  }
+
   /**
    * Returns an effectively unlimited stream of pseudorandom triples of int values, without
    * replacement, from the interval [0, n). Each triple is sorted in increasing order. <b>Enhanced