From be9b6bc699de0f20722507fc448b1473f89ac346 Mon Sep 17 00:00:00 2001 From: "Vincent A. Cicirello" Date: Wed, 3 Aug 2022 12:08:29 -0400 Subject: [PATCH 1/2] permutation operators interfaces and apply method --- .../cicirello/permutations/Permutation.java | 22 +++++++ .../PermutationFullBinaryOperator.java | 59 +++++++++++++++++++ .../PermutationFullUnaryOperator.java | 52 ++++++++++++++++ .../permutations/PermutationTestCases.java | 29 +++++++++ 4 files changed, 162 insertions(+) create mode 100644 src/main/java/org/cicirello/permutations/PermutationFullBinaryOperator.java create mode 100644 src/main/java/org/cicirello/permutations/PermutationFullUnaryOperator.java 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. From 19f080bef1b8b573606fd9dea101ae6d74759f7b Mon Sep 17 00:00:00 2001 From: "Vincent A. Cicirello" Date: Wed, 3 Aug 2022 12:11:55 -0400 Subject: [PATCH 2/2] Update CHANGELOG.md --- CHANGELOG.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) 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