Merge pull request #230 from cicirello/feat-ops

Added PermutationFullUnaryOperator and PermutationFullBinaryOperator

Author: cicirello

CHANGELOG.md

@@ -4,9 +4,15 @@ 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-07-24
+## [Unreleased] - 2022-08-03
 
 ### Added
+* PermutationFullUnaryOperator and PermutationFullBinaryOperator functional interfaces for the purpose
+  of specifying custom operations on Permutation objects. These are variations of the existing
+  PermutationUnaryOperator and PermutationBinaryOperator interfaces that were added in 3.2.0, but with 
+  both the raw int arrays and Permutation objects passed to the operators.
+* Permutation.apply methods, one for each of the two new PermutationFullUnaryOperator 
+  and PermutationFullBinaryOperator interfaces, for applying such custom Permutation operators.
 
 ### Changed
 

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

@@ -208,6 +208,15 @@ public void apply(PermutationUnaryOperator operator) {
 		operator.apply(permutation);
 	}
 
+	/**
+	 * Applies a custom unary operator on a Permutation object.
+	 *
+	 * @param operator A unary Permutation operator
+	 */
+	public void apply(PermutationFullUnaryOperator operator) {
+		operator.apply(permutation, this);
+	}
+	
 	/**
 	 * 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
@@ -221,6 +230,19 @@ public void apply(PermutationBinaryOperator operator, Permutation other) {
 		operator.apply(permutation, other.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, and this and other are passed as p1 and p2, respectively.
+	 *
+	 * @param operator A binary Permutation operator
+	 * @param other The other Permutation
+	 */
+	public void apply(PermutationFullBinaryOperator operator, Permutation other) {
+		operator.apply(permutation, other.permutation, this, other);
+	}
+	
 	/**
 	 * Creates an identical copy of this object.
 	 * @return an identical copy of this object

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

@@ -0,0 +1,59 @@
+/*
+ * 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(PermutationFullBinaryOperator,Permutation)} method.
+ * In this interface, the {@link #apply} method is passed both references to the raw arrays
+ * of ints that are encapsulated by the Permutations, as well as references to the original
+ * Permutation objects to enable utilizing the methods of the {@link Permutation}
+ * class. If the operator that you are implementing only requires the raw arrays of ints,
+ * then consider implementing the {@link PermutationBinaryOperator} interface instead.
+ *
+ * @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 PermutationFullBinaryOperator {
+	
+	/**
+	 * 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.
+	 *
+	 * @param p1 A reference to the Permutation object that encapsulates rawPermutation1.
+	 *
+	 * @param p2 A reference to the Permutation object that encapsulates rawPermutation2.
+	 */
+	void apply(int[] rawPermutation1, int[] rawPermutation2, Permutation p1, Permutation p2);
+}

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

@@ -0,0 +1,52 @@
+/*
+ * 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(PermutationFullUnaryOperator)} method. In this
+ * interface, the {@link #apply} method is passed both a reference to the raw array
+ * of ints that is encapsulated by the Permutation, as well as a reference to the
+ * Permutation object itself to enable utilizing the methods of the {@link Permutation}
+ * class. If the operator that you are implementing only requires the raw array of ints,
+ * then consider implementing the {@link PermutationUnaryOperator} interface instead.
+ *
+ * @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 PermutationFullUnaryOperator {
+	
+	/**
+	 * 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.
+	 *
+	 * @param p A reference to the Permutation object that encapsulates it.
+	 */
+	void apply(int[] rawPermutation, Permutation p);
+}

src/test/java/org/cicirello/permutations/PermutationTestCases.java

@@ -72,6 +72,35 @@ public void testBinaryOperator() {
 		}
 	}
 
+	@Test
+	public void testFullUnaryOperator() {
+		Permutation p = new Permutation(10);
+		p.apply((perm, original) -> { for (int i = 0; i < perm.length; i++) { perm[i] = i; assertEquals(perm[i], original.get(i)); }});
+		for (int i = 0; i < 10; i++) {
+			assertEquals(i, p.get(i));
+		}
+		p.apply((perm, original) -> { for (int i = 0; i < perm.length; i++) { perm[perm.length-1-i] = i; assertEquals(perm[perm.length-1-i], original.get(perm.length-1-i)); }});
+		for (int i = 0; i < 10; i++) {
+			assertEquals(9-i, p.get(i));
+		}
+	}
+	
+	@Test
+	public void testFullBinaryOperator() {
+		Permutation p1 = new Permutation(10);
+		Permutation p2 = new Permutation(10);
+		p1.apply((perm1, perm2, o1, o2) -> { for (int i = 0; i < perm1.length; i++) { perm1[i] = i; perm2[perm1.length-1-i] = i; assertEquals(i, o1.get(i)); assertEquals(i, o2.get(9-i)); }}, p2);
+		for (int i = 0; i < 10; i++) {
+			assertEquals(i, p1.get(i));
+			assertEquals(9-i, p2.get(i));
+		}
+		p1.apply((perm1, perm2, o1, o2) -> { for (int i = 0; i < perm1.length; i++) { perm2[i] = i; perm1[perm1.length-1-i] = i; assertEquals(i, o2.get(i)); assertEquals(i, o1.get(9-i)); }}, p2);
+		for (int i = 0; i < 10; i++) {
+			assertEquals(i, p2.get(i));
+			assertEquals(9-i, p1.get(i));
+		}
+	}
+	
 	@Test
 	public void testZeroLengthPermutations() {
 		// different ways of constructing 0 length permutations.