Merge pull request #406 from cicirello/update-based-on-rhomu

Optimized Permutation.scramble methods

Author: cicirello

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-14
+## [Unreleased] - 2024-05-15
 
 **Breaking Changes**: Due to breaking changes, the next release will be a major release (see the Removed section below for details). Timing of that major release will likely be in the Fall of 2023 to coincide with the planned transition to Java 21 upon its release.
 
@@ -21,6 +21,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   * org.cicirello.sequences.distance.EditDistance
   * org.cicirello.sequences.distance.EditDistanceDouble
 * Refactored to improve code quality and to optimize SequenceReservoirSampler, SequencePoolSampler, SequenceInsertionSampler, SequenceCompositeSampler.
+* Minor optimizations to Permutation.scramble() methods.
 
 ### Deprecated
 

README.md

@@ -2,7 +2,7 @@
 
 [![JavaPermutationTools - A Java library for computation on permutations and sequences](https://jpt.cicirello.org/images/jpt640.png)](#javapermutationtools-jpt-a-java-library-for-computation-on-permutations-and-sequences)
 
-Copyright (C) 2018-2023 [Vincent A. Cicirello](https://www.cicirello.org/).
+Copyright (C) 2018-2024 [Vincent A. Cicirello](https://www.cicirello.org/).
 
 Website: https://jpt.cicirello.org/
 

pom.xml

@@ -30,7 +30,7 @@
 			<distribution>repo</distribution>
 			<comments>
 			JavaPermutationTools (JPT): A library for computation on permutations and sequences.
-			Copyright (C) 2005-2023 Vincent A. Cicirello.
+			Copyright (C) 2005-2024 Vincent A. Cicirello.
 
 			JavaPermutationTools is free software: you can redistribute it and/or modify
 			it under the terms of the GNU General Public License as published by
@@ -283,7 +283,7 @@
 						<link>https://rho-mu.cicirello.org/api</link>
 						<link>https://core.cicirello.org/api</link>
 					</links>
-					<bottom><![CDATA[Copyright &copy; 2005-2023 <a href=\"https://www.cicirello.org/\" target=_top>Vincent A. Cicirello</a>.  All rights reserved.]]></bottom>
+					<bottom><![CDATA[Copyright &copy; 2005-2024 <a href=\"https://www.cicirello.org/\" target=_top>Vincent A. Cicirello</a>.  All rights reserved.]]></bottom>
 				</configuration>
 			</plugin>
 			<plugin>

src/main/java/org/cicirello/permutations/Permutation.java

@@ -1,6 +1,6 @@
 /*
  * JavaPermutationTools: A Java library for computation on permutations and sequences
- * Copyright 2005-2023 Vincent A. Cicirello, <https://www.cicirello.org/>.
+ * Copyright 2005-2024 Vincent A. Cicirello, <https://www.cicirello.org/>.
  *
  * This file is part of JavaPermutationTools (https://jpt.cicirello.org/).
  *
@@ -497,8 +497,9 @@ public void scramble(boolean guaranteeDifferent) {
   public void scramble(RandomGenerator r, boolean guaranteeDifferent) {
     if (guaranteeDifferent) {
       boolean changed = false;
-      for (int i = permutation.length - 1; i > 1; i--) {
-        int j = RandomIndexer.nextInt(i + 1, r);
+      for (int j = permutation.length; j > 2; ) {
+        int i = RandomIndexer.nextInt(j, r);
+        j--;
         if (i != j) {
           internalSwap(i, j);
           changed = true;
@@ -515,7 +516,8 @@ public void scramble(RandomGenerator r, boolean guaranteeDifferent) {
 
   /**
    * Randomly shuffles a segment. Uses {@link ThreadLocalRandom} as the source of efficient random
-   * number generation.
+   * number generation. As long as two different indexes are passed to this method, it is guaranteed
+   * to change the permutation.
    *
    * @param i endpoint of the segment (precondition: 0 &le; i &lt; length())
    * @param j endpoint of the segment (precondition: 0 &le; j &lt; length())
@@ -527,7 +529,8 @@ public void scramble(int i, int j) {
   }
 
   /**
-   * Randomly shuffles a segment.
+   * Randomly shuffles a segment. As long as two different indexes are passed to this method, it is
+   * guaranteed to change the permutation.
    *
    * @param i endpoint of the segment (precondition: 0 &le; i &lt; length())
    * @param j endpoint of the segment (precondition: 0 &le; j &lt; length())
@@ -574,8 +577,9 @@ public void scramble(int i, int j, RandomGenerator r) {
   public void scramble(int[] indexes, RandomGenerator r) {
     if (indexes.length > 1) {
       boolean changed = false;
-      for (int j = indexes.length - 1; j > 1; j--) {
-        int i = RandomIndexer.nextInt(j + 1, r);
+      for (int j = indexes.length; j > 2; ) {
+        int i = RandomIndexer.nextInt(j, r);
+        j--;
         if (i != j) {
           internalSwap(indexes[i], indexes[j]);
           changed = true;
@@ -603,10 +607,10 @@ public void scramble(int[] indexes) {
   }
 
   /**
-   * Retrieves the i'th integer of the permutation.
+   * Retrieves the i-th integer of the permutation.
    *
    * @param i the index of the integer to retrieve. (precondition: 0 &le; i &lt; length())
-   * @return the integer in the i'th position.
+   * @return the integer in the i-th position.
    * @throws ArrayIndexOutOfBoundsException if i is negative, or if i is greater than or equal to
    *     length()
    */