Merge pull request #190 from cicirello/feat-visitor

Added PermutationUnaryOperator and PermutationBinaryOperator interfaces and related

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] - 2022-02-17
+## [Unreleased] - 2022-03-17
 
 ### Added
 
@@ -21,6 +21,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Other
 
 
+## [3.2.0] - 2022-03-17
+
+### Added
+* PermutationUnaryOperator and PermutationBinaryOperator functional interfaces for the purpose
+  of specifying custom operations on Permutation objects.
+* Permutation.apply methods, one for each of the two new PermutationUnaryOperator 
+  and PermutationBinaryOperator interfaces, for applying such custom Permutation operators.
+
+### Changed
+* Various improvements to the documentation.
+
+### Deprecated
+* The Permutation.Mechanic nested class, which will be removed in the next 
+  major release 4.0.0. The new Permutation.apply methods should be used instead.
+
+
 ## [3.1.1] - 2022-02-17
 
 ### Fixed

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

@@ -1,5 +1,6 @@
 /*
- * Copyright 2005, 2010, 2014-2021 Vincent A. Cicirello, <https://www.cicirello.org/>.
+ * JavaPermutationTools: A Java library for computation on permutations and sequences
+ * Copyright 2005-2022 Vincent A. Cicirello, <https://www.cicirello.org/>.
  *
  * This file is part of JavaPermutationTools (https://jpt.cicirello.org/).
  *
@@ -17,7 +18,6 @@
  *
  * You should have received a copy of the GNU General Public License
  * along with JavaPermutationTools.  If not, see <http://www.gnu.org/licenses/>.
- *
  */
 package org.cicirello.permutations;
 
@@ -37,13 +37,15 @@
  * This class provides the functionality to generate random permutations, and to
  * manipulate permutations in a variety of ways.
  * 
- * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, <a href=https://www.cicirello.org/ target=_top>https://www.cicirello.org/</a> 
- * @version 3.31.2021
+ * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, 
+ * <a href=https://www.cicirello.org/ target=_top>https://www.cicirello.org/</a> 
  */
 public final class Permutation implements Serializable, Iterable<Permutation>, Copyable<Permutation> {
 
 	private static final long serialVersionUID = 1L;
 
+	private final int[] permutation;
+	
 	/**
 	 * Initializes a random permutation of n integers.  Uses
 	 * java.util.concurrent.ThreadLocalRandom as the source of efficient random number generation.
@@ -205,6 +207,28 @@ public Permutation(Permutation p, int length) {
 		}
 	}
 
+	/**
+	 * Applies a custom unary operator on a Permutation object.
+	 *
+	 * @param operator A unary Permutation operator
+	 */
+	public void apply(PermutationUnaryOperator operator) {
+		operator.apply(permutation);
+	}
+	
+	/**
+	 * Applies a custom binary operator on a pair of Permutation objects.
+	 * The raw int array belonging to this is passed as the first array to
+	 * operator.apply() and the raw int array belonging to other is passed
+	 * as the second.
+	 *
+	 * @param operator A binary Permutation operator
+	 * @param other The other Permutation
+	 */
+	public void apply(PermutationBinaryOperator operator, Permutation other) {
+		operator.apply(permutation, other.permutation);
+	}
+	
 	/**
 	 * Creates an identical copy of this object.
 	 * @return an identical copy of this object
@@ -904,8 +928,6 @@ public int hashCode() {
 		return Arrays.hashCode(permutation);
 	}
 
-	private final int[] permutation;
-	
 	/**
 	 * <p>The Permutation.Mechanic class provides a means of adding application-specific
 	 * operations on Permutations without the need to directly alter the Permutation
@@ -937,10 +959,15 @@ public int hashCode() {
 	 * a public method of Subclass can similarly, temporarily, create a non-functioning Permutation.  However,
 	 * that public method is expected to ensure that the Permutation is fully valid before returning.</p>
 	 *
-	 * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, <a href=https://www.cicirello.org/ target=_top>https://www.cicirello.org/</a> 
-	 * @version 3.31.2021
+	 * @deprecated This class will be removed in the next major release, 4.0.0, and you should instead
+	 *    use the functionality provided by the {@link Permutation#apply(PermutationUnaryOperator)} and
+	 *    {@link Permutation#apply(PermutationBinaryOperator,Permutation)} methods, and the related
+	 *    {@link PermutationUnaryOperator} and {@link PermutationBinaryOperator} interfaces.
+	 *
+	 * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, 
+	 * <a href=https://www.cicirello.org/ target=_top>https://www.cicirello.org/</a> 
 	 */
-	public static class Mechanic {
+	@Deprecated public static class Mechanic {
 
 		/**
 		 * The default constructor can only be called by subclasses.

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

@@ -0,0 +1,50 @@
+/*
+ * JavaPermutationTools: A Java library for computation on permutations and sequences
+ * Copyright 2005-2022 Vincent A. Cicirello, <https://www.cicirello.org/>.
+ *
+ * This file is part of JavaPermutationTools (https://jpt.cicirello.org/).
+ *
+ * JavaPermutationTools is free software: you can 
+ * redistribute it and/or modify it under the terms of the GNU 
+ * General Public License as published by the Free Software 
+ * Foundation, either version 3 of the License, or (at your 
+ * option) any later version.
+ *
+ * JavaPermutationTools is distributed in the hope 
+ * that it will be useful, but WITHOUT ANY WARRANTY; without even 
+ * the implied warranty of MERCHANTABILITY or FITNESS FOR A 
+ * PARTICULAR PURPOSE.  See the GNU General Public License for more 
+ * details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with JavaPermutationTools.  If not, see <http://www.gnu.org/licenses/>.
+ */
+package org.cicirello.permutations;
+
+/**
+ * A functional interface for defining custom binary operators on Permutations.
+ * See the {@link Permutation#apply(PermutationBinaryOperator,Permutation)} method.
+ *
+ * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, 
+ * <a href=https://www.cicirello.org/ target=_top>https://www.cicirello.org/</a> 
+ */
+@FunctionalInterface
+public interface PermutationBinaryOperator {
+	
+	/**
+	 * Applies an operator on the raw representations of
+	 * a pair of Permutations. Implementers of this interface are responsible
+	 * for ensuring that the apply method maintains valid
+	 * permutations of the integers in {0, 1, ..., rawPermutation1.length - 1 },
+	 * and likewise for rawPermutation2.
+	 *
+	 * @param rawPermutation1 A reference to the raw array of ints underlying a
+	 * Permutation object. Changes to this array will directly change the Permutation
+	 * object that encapsulates it.
+	 *
+	 * @param rawPermutation2 A reference to the raw array of ints underlying a
+	 * Permutation object. Changes to this array will directly change the Permutation
+	 * object that encapsulates it.
+	 */
+	void apply(int[] rawPermutation1, int[] rawPermutation2);
+}

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

@@ -1,5 +1,6 @@
 /*
- * Copyright 2018-2022 Vincent A. Cicirello, <https://www.cicirello.org/>.
+ * JavaPermutationTools: A Java library for computation on permutations and sequences
+ * Copyright 2005-2022 Vincent A. Cicirello, <https://www.cicirello.org/>.
  *
  * This file is part of JavaPermutationTools (https://jpt.cicirello.org/).
  *
@@ -31,7 +32,8 @@
  * of swaps it returns a copy (an O(n) operation) of the internally maintained Permutation object so the caller can safely
  * modify the returned Permutation without risk of interfering with the operation of the Iterator.
  *
- * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, <a href=https://www.cicirello.org/ target=_top>https://www.cicirello.org/</a> 
+ * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, 
+ * <a href=https://www.cicirello.org/ target=_top>https://www.cicirello.org/</a> 
  */
 public class PermutationIterator implements Iterator<Permutation> {
 

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

@@ -0,0 +1,45 @@
+/*
+ * JavaPermutationTools: A Java library for computation on permutations and sequences
+ * Copyright 2005-2022 Vincent A. Cicirello, <https://www.cicirello.org/>.
+ *
+ * This file is part of JavaPermutationTools (https://jpt.cicirello.org/).
+ *
+ * JavaPermutationTools is free software: you can 
+ * redistribute it and/or modify it under the terms of the GNU 
+ * General Public License as published by the Free Software 
+ * Foundation, either version 3 of the License, or (at your 
+ * option) any later version.
+ *
+ * JavaPermutationTools is distributed in the hope 
+ * that it will be useful, but WITHOUT ANY WARRANTY; without even 
+ * the implied warranty of MERCHANTABILITY or FITNESS FOR A 
+ * PARTICULAR PURPOSE.  See the GNU General Public License for more 
+ * details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with JavaPermutationTools.  If not, see <http://www.gnu.org/licenses/>.
+ */
+package org.cicirello.permutations;
+
+/**
+ * A functional interface for defining custom unary operators on Permutations.
+ * See the {@link Permutation#apply(PermutationUnaryOperator)} method.
+ *
+ * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, 
+ * <a href=https://www.cicirello.org/ target=_top>https://www.cicirello.org/</a> 
+ */
+@FunctionalInterface
+public interface PermutationUnaryOperator {
+	
+	/**
+	 * Applies an operator on the raw representation of
+	 * a Permutation. Implementers of this interface are responsible
+	 * for ensuring that the apply method maintains a valid
+	 * permutation of the integers in {0, 1, ..., rawPermutation.length - 1 }.
+	 *
+	 * @param rawPermutation A reference to the raw array of ints underlying a
+	 * Permutation object. Changes to this array will directly change the Permutation
+	 * object that encapsulates it.
+	 */
+	void apply(int[] rawPermutation);
+}

src/main/java/org/cicirello/permutations/distance/AcyclicEdgeDistance.java

@@ -1,7 +1,6 @@
 /*
- * Copyright 2014-2021 Vincent A. Cicirello, <https://www.cicirello.org/>.
- *
- * This file is part of JavaPermutationTools (https://jpt.cicirello.org/).
+ * JavaPermutationTools - A Java library for computation on permutations.
+ * Copyright 2005-2022 Vincent A. Cicirello, <https://www.cicirello.org/>.
  *
  * JavaPermutationTools is free software: you can 
  * redistribute it and/or modify it under the terms of the GNU 
@@ -17,13 +16,12 @@
  *
  * You should have received a copy of the GNU General Public License
  * along with JavaPermutationTools.  If not, see <http://www.gnu.org/licenses/>.
+ *
  */
 package org.cicirello.permutations.distance;
 
 import org.cicirello.permutations.Permutation;
 /**
- * Acyclic Edge Distance:
- *
  * <p>Acyclic edge distance treats the permutations as if they represent sets of edges, and counts
  * the number of edges that differ.</p>
  *
@@ -41,8 +39,8 @@
  * <p>Acyclic edge distance was first described in:<br>
  * S. Ronald, "Distance functions for order-based encodings," in Proc. IEEE CEC. IEEE Press, 1997, pp. 49–54.</p>
  *
- * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, <a href=https://www.cicirello.org/ target=_top>https://www.cicirello.org/</a>
- * @version 4.2.2021
+ * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, 
+ * <a href=https://www.cicirello.org/ target=_top>https://www.cicirello.org/</a>
  */
 public final class AcyclicEdgeDistance implements NormalizedPermutationDistanceMeasurer {
 

src/main/java/org/cicirello/permutations/distance/BlockInterchangeDistance.java

@@ -1,7 +1,6 @@
 /*
- * Copyright 2019, 2021 Vincent A. Cicirello, <https://www.cicirello.org/>.
- *
- * This file is part of JavaPermutationTools (https://jpt.cicirello.org/).
+ * JavaPermutationTools - A Java library for computation on permutations.
+ * Copyright 2005-2022 Vincent A. Cicirello, <https://www.cicirello.org/>.
  *
  * JavaPermutationTools is free software: you can 
  * redistribute it and/or modify it under the terms of the GNU 
@@ -17,14 +16,13 @@
  *
  * You should have received a copy of the GNU General Public License
  * along with JavaPermutationTools.  If not, see <http://www.gnu.org/licenses/>.
+ *
  */
 package org.cicirello.permutations.distance;
 
 import org.cicirello.permutations.Permutation;
 
 /**
- * Block Interchange Distance:
- *
  * <p>Block Interchange Distance is the minimum number of block interchanges 
  * necessary to transform one permutation into the other.  A block interchange is
  * an edit operation that takes two non-overlapping blocks (i.e., subsequence)
@@ -39,8 +37,8 @@
  *
  * <p>Runtime: O(n), where n is the permutation length.</p>
  *
- * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, <a href=https://www.cicirello.org/ target=_top>https://www.cicirello.org/</a>
- * @version 4.2.2021
+ * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, 
+ * <a href=https://www.cicirello.org/ target=_top>https://www.cicirello.org/</a>
  */
 public class BlockInterchangeDistance implements NormalizedPermutationDistanceMeasurer {
 

src/main/java/org/cicirello/permutations/distance/CyclicEdgeDistance.java

@@ -1,7 +1,6 @@
 /*
- * Copyright 2014-2021 Vincent A. Cicirello, <https://www.cicirello.org/>.
- *
- * This file is part of JavaPermutationTools (https://jpt.cicirello.org/).
+ * JavaPermutationTools - A Java library for computation on permutations.
+ * Copyright 2005-2022 Vincent A. Cicirello, <https://www.cicirello.org/>.
  *
  * JavaPermutationTools is free software: you can 
  * redistribute it and/or modify it under the terms of the GNU 
@@ -17,13 +16,12 @@
  *
  * You should have received a copy of the GNU General Public License
  * along with JavaPermutationTools.  If not, see <http://www.gnu.org/licenses/>.
+ *
  */
 package org.cicirello.permutations.distance;
 
 import org.cicirello.permutations.Permutation;
 /**
- * Cyclic Edge Distance:
- *
  * <p>Cyclic edge distance treats the permutations as if they represent sets of edges, and counts
  * the number of edges that differ.  It treats the last to the first element as an edge.</p>
  *
@@ -41,8 +39,8 @@
  * <p>Cyclic edge distance was first described in:<br>
  * S. Ronald, "Distance functions for order-based encodings," in Proc. IEEE CEC. IEEE Press, 1997, pp. 49–54.</p>
  *
- * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, <a href=https://www.cicirello.org/ target=_top>https://www.cicirello.org/</a>
- * @version 4.2.2021
+ * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, 
+ * <a href=https://www.cicirello.org/ target=_top>https://www.cicirello.org/</a>
  */
 public final class CyclicEdgeDistance implements NormalizedPermutationDistanceMeasurer {
 

src/main/java/org/cicirello/permutations/distance/CyclicIndependentDistance.java

@@ -1,7 +1,6 @@
 /*
- * Copyright 2018-2021 Vincent A. Cicirello, <https://www.cicirello.org/>.
- *
- * This file is part of JavaPermutationTools (https://jpt.cicirello.org/).
+ * JavaPermutationTools - A Java library for computation on permutations.
+ * Copyright 2005-2022 Vincent A. Cicirello, <https://www.cicirello.org/>.
  *
  * JavaPermutationTools is free software: you can 
  * redistribute it and/or modify it under the terms of the GNU 
@@ -17,6 +16,7 @@
  *
  * You should have received a copy of the GNU General Public License
  * along with JavaPermutationTools.  If not, see <http://www.gnu.org/licenses/>.
+ *
  */
 package org.cicirello.permutations.distance;
 
@@ -31,9 +31,8 @@
  * to rotations of p2, where the underlying distance measure is passed as a parameter to
  * the constructor.</p>
  *
- * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, <a href=https://www.cicirello.org/ target=_top>https://www.cicirello.org/</a>
- * @version 4.2.2021
- *  
+ * @author <a href=https://www.cicirello.org/ target=_top>Vincent A. Cicirello</a>, 
+ * <a href=https://www.cicirello.org/ target=_top>https://www.cicirello.org/</a>  
  */
 public final class CyclicIndependentDistance implements PermutationDistanceMeasurer {