diff --git a/CHANGELOG.md b/CHANGELOG.md
index 099ad22d..aa68f02b 100644
--- a/CHANGELOG.md
+++ b/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
diff --git a/src/main/java/org/cicirello/permutations/Permutation.java b/src/main/java/org/cicirello/permutations/Permutation.java
index 0fa53dbb..22fe2c29 100644
--- a/src/main/java/org/cicirello/permutations/Permutation.java
+++ b/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
diff --git a/src/main/java/org/cicirello/permutations/PermutationFullBinaryOperator.java b/src/main/java/org/cicirello/permutations/PermutationFullBinaryOperator.java
new file mode 100644
index 00000000..e8fee0b3
--- /dev/null
+++ b/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, .
+ *
+ * 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 .
+ */
+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 Vincent A. Cicirello,
+ * https://www.cicirello.org/
+ */
+@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);
+}
diff --git a/src/main/java/org/cicirello/permutations/PermutationFullUnaryOperator.java b/src/main/java/org/cicirello/permutations/PermutationFullUnaryOperator.java
new file mode 100644
index 00000000..18b65767
--- /dev/null
+++ b/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, .
+ *
+ * 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 .
+ */
+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 Vincent A. Cicirello,
+ * https://www.cicirello.org/
+ */
+@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);
+}
diff --git a/src/test/java/org/cicirello/permutations/PermutationTestCases.java b/src/test/java/org/cicirello/permutations/PermutationTestCases.java
index 8c06bfc8..8395a35e 100644
--- a/src/test/java/org/cicirello/permutations/PermutationTestCases.java
+++ b/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.