Merge pull request #291 from cicirello/improve-windowed-triple

Various improvements to generating random triples of integers

CHANGELOG.md

@@ -4,7 +4,7 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased] - 2024-05-07
+## [Unreleased] - 2024-05-09
 
 **BREAKING CHANGES: See Removed and Changed sections for details.**
 
@@ -14,12 +14,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Versions of nextIntPair methods that utilize the new IndexPair class added to both RandomIndexer and EnhancedRandomGenerator classes.
 * Versions of nextIntTriple methods that utilize the new IndexTriple class added to both RandomIndexer and EnhancedRandomGenerator classes.
 * Versions of nextWindowedIntPair methods that utilize the new IndexPair class added to both RandomIndexer and EnhancedRandomGenerator classes.
+* Versions of nextWindowedIntTriple methods that utilize the new IndexTriple class added to both RandomIndexer and EnhancedRandomGenerator classes.
 * Streams of random pairs of distinct integers as streams of IndexPair objects.
 * Streams of random triples of distinct integers as streams of IndexTriple objects.
+* Streams of random triples of distinct sorted integers as streams of IndexTriple objects.
+* RandomIndexer.nextSortedIntTriple and EnhancedRandomGenerator.nextSortedIntTriple methods: variation of nextIntTriple whose result is in sorted order.
+* RandomIndexer.nextSortedWindowedIntTriple and EnhancedRandomGenerator.nextSortedWindowedIntTriple: variation of RandomIndexer.nextWindowedIntTriple method whose result is in sorted order.
 
 ### Changed
 * Refactored and optimized RandomIndexer.nextIntTriple methods.
 * Refactored and optimized RandomIndexer.nextWindowedIntPair methods.
+* Refactored and optimized RandomIndexer.nextWindowedIntTriple methods.
 * Changed ZigguratGaussian to a package-access class (BREAKING CHANGE).
 
 ### Deprecated

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

@@ -500,20 +500,19 @@ public final 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. <b>Enhanced Functionality.</b>
+   * interval [0, n). All n choose 3 combinations are equally likely. The result is sorted in
+   * increasing order. <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 triple 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.
-   * @param sort If true, the result is sorted in increasing order; otherwise it is in arbitrary
-   *     order.
    * @return An array containing the triple of randomly chosen integers from the interval [0, n).
    * @throws IllegalArgumentException if n &lt; 3.
    */
-  public final int[] nextIntTriple(int n, int[] result, boolean sort) {
-    return RandomIndexer.nextIntTriple(n, result, sort, generator);
+  public final int[] nextSortedIntTriple(int n, int[] result) {
+    return RandomIndexer.nextSortedIntTriple(n, result, generator);
   }
 
   /**
@@ -532,18 +531,17 @@ public final 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. <b>Enhanced Functionality.</b>
+   * interval [0, n). All n choose 3 combinations are equally likely. The result is sorted in
+   * increasing order. <b>Enhanced Functionality.</b>
    *
    * <p>The runtime is O(1).
    *
    * @param n The number of integers to choose from.
-   * @param sort If true, the result is sorted in increasing order; otherwise it is in arbitrary
-   *     order.
    * @return A triple of randomly chosen integers from the interval [0, n).
    * @throws IllegalArgumentException if n &lt; 3.
    */
-  public final IndexTriple nextIntTriple(int n, boolean sort) {
-    return RandomIndexer.nextIntTriple(n, sort, generator);
+  public final IndexTriple nextSortedIntTriple(int n) {
+    return RandomIndexer.nextSortedIntTriple(n, generator);
   }
 
   /**
@@ -612,15 +610,50 @@ public final int[] nextWindowedIntTriple(int n, int window, int[] result) {
    *
    * @param n The number of integers to choose from.
    * @param window The maximum difference between the integers of the triple.
+   * @return A triple of randomly chosen integers, i, j, k from the interval [0, n), such that |i-j|
+   *     &le; window, and |i-k| &le; window, and |k-j| &le; window.
+   * @throws IllegalArgumentException if window &lt; 2 or n &lt; 3.
+   */
+  public final IndexTriple nextWindowedIntTriple(int n, int window) {
+    return RandomIndexer.nextWindowedIntTriple(n, window, generator);
+  }
+
+  /**
+   * 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| &le; window, and |i-k| &le; window, and |k-j| &le;
+   * window. All triples that satisfy the window constraint are equally likely. The result is sorted
+   * in increasing order. <b>Enhanced Functionality.</b>
+   *
+   * <p>The runtime is O(1).
+   *
+   * @param n The number of integers to choose from.
+   * @param window The maximum difference between the integers of the triple.
    * @param result An array to hold the triple 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.
-   * @param sort If true, the result is sorted in increasing order, otherwise it is in random order.
    * @return An array containing the triple of randomly chosen integers, i, j, k from the interval
    *     [0, n), such that |i-j| &le; window, and |i-k| &le; window, and |k-j| &le; window.
    * @throws IllegalArgumentException if window &lt; 2 or n &lt; 3.
    */
-  public final int[] nextWindowedIntTriple(int n, int window, int[] result, boolean sort) {
-    return RandomIndexer.nextWindowedIntTriple(n, window, result, sort, generator);
+  public final int[] nextSortedWindowedIntTriple(int n, int window, int[] result) {
+    return RandomIndexer.nextSortedWindowedIntTriple(n, window, result, generator);
+  }
+
+  /**
+   * 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| &le; window, and |i-k| &le; window, and |k-j| &le;
+   * window. All triples that satisfy the window constraint are equally likely. The result is sorted
+   * in increasing order. <b>Enhanced Functionality.</b>
+   *
+   * <p>The runtime is O(1).
+   *
+   * @param n The number of integers to choose from.
+   * @param window The maximum difference between the integers of the triple.
+   * @return A triple of randomly chosen integers, i, j, k from the interval [0, n), such that |i-j|
+   *     &le; window, and |i-k| &le; window, and |k-j| &le; window.
+   * @throws IllegalArgumentException if window &lt; 2 or n &lt; 3.
+   */
+  public final IndexTriple nextSortedWindowedIntTriple(int n, int window) {
+    return RandomIndexer.nextSortedWindowedIntTriple(n, window, generator);
   }
 
   /**
@@ -789,31 +822,28 @@ public final Stream<IndexTriple> triples(long streamSize, int n) {
 
   /**
    * Returns an effectively unlimited stream of pseudorandom triples of int values, without
-   * replacement, from the interval [0, n). <b>Enhanced Functionality.</b>
+   * replacement, from the interval [0, n). Each triple is sorted in increasing order. <b>Enhanced
+   * Functionality.</b>
    *
    * @param n bound on random values, exclusive.
-   * @param sort If true, the result is sorted in increasing order; otherwise it is in arbitrary
-   *     order.
    * @return an effectively unlimited stream of pseudorandom triples of int values, without
    *     replacement, from the interval [0, n).
    */
-  public final Stream<IndexTriple> triples(int n, boolean sort) {
-    return Stream.generate(() -> nextIntTriple(n, sort)).sequential();
+  public final Stream<IndexTriple> sortedTriples(int n) {
+    return Stream.generate(() -> nextSortedIntTriple(n)).sequential();
   }
 
   /**
    * Returns a stream of pseudorandom triples of int values, without replacement, from the interval
-   * [0, n). <b>Enhanced Functionality.</b>
+   * [0, n). Each triple is sorted in increasing order. <b>Enhanced Functionality.</b>
    *
    * @param streamSize The number of values in the stream.
    * @param n bound on random values, exclusive.
-   * @param sort If true, the result is sorted in increasing order; otherwise it is in arbitrary
-   *     order.
    * @return a stream of pseudorandom triples of int values, without replacement, from the interval
    *     [0, n).
    */
-  public final Stream<IndexTriple> triples(long streamSize, int n, boolean sort) {
-    return Stream.generate(() -> nextIntTriple(n, sort)).sequential().limit(streamSize);
+  public final Stream<IndexTriple> sortedTriples(long streamSize, int n) {
+    return Stream.generate(() -> nextSortedIntTriple(n)).sequential().limit(streamSize);
   }
 
   // METHODS THAT CHANGE FUNCTIONALITY: