Skip to content

Removed Permutation.Mechanic nested class #217

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jun 2, 2022
Merged

Removed Permutation.Mechanic nested class #217

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ac2774f
removed Permutation.Mechanic
cicirello Jun 2, 2022
d97ed60
Update CHANGELOG.md
cicirello Jun 2, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ details below.
### Deprecated

### Removed
* Permutation.Mechanic nested class previously deprecated in v3.2.0 (breaking change).

### Fixed

Expand Down
114 changes: 0 additions & 114 deletions src/main/java/org/cicirello/permutations/Permutation.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -930,118 +930,4 @@ public boolean equals(Object other) {
public int hashCode() {
return Arrays.hashCode(permutation);
}

/**
* <p>The Permutation.Mechanic class provides a means of adding application-specific
* operations on Permutations without the need to directly alter the Permutation
* class. It is similar to a Visitor from the Visitor pattern.</p>
*
* <p>The methods of the Permutation.Mechanic class are unsafe, and if used incorrectly
* can result in invalid Permutation state, and/or runtime exceptions. The methods of
* this nested class do not perform any bounds checks. Additionally, they do not check
* whether the usage produces a valid permutation.</p>
*
* <p>The Permutation.Mechanic class cannot be instantiated directly. To use, you must
* define a subtype by extending the Permutation.Mechanic class. It is the responsibility
* of the subclass to ensure that all of the methods of the subclass are safe. For example,
* one of the set methods of the Permutation.Mechanic class enables setting a specific
* index of a Permutation to any integer value. Individual calls to that method will
* produce an invalid Permutation. It is the responsibility of any public method of the subclass to ensure
* that a combination of calls to the set method is performed that results in a valid Permutation by the
* time that subclass method returns.</p>
*
* <p>Here's the Mechanic analogy: Imagine that you take your car in for service. The mechanic
* opens the hood, and starts disconnecting and removing stuff. During much of that time,
* your car is inoperable. However, by the time you pick up your car, it has been put back
* together properly, and is in functioning order. Perhaps it has new tires, or a new timing belt, etc,
* so its state has changed.</p>
*
* <p>Consider a subclass, Subclass, of the Permutation.Mechanic. An object of Subclass is like a mechanic,
* and the Permutation passed to its methods is the car. Each call to a public method of Subclass is like
* a visit to the service station. Just like a mechanic can take your car apart during that service visit,
* 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>
*
* @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>
*/
@Deprecated public static class Mechanic {

/**
* The default constructor can only be called by subclasses.
*/
protected Mechanic() {}

/**
* Changes the state of the Permutation according to the contents
* of an array of int values. The caller of this method is responsible
* to ensure that the array is the same length as the Permutation,
* and that the elements are a valid permutation of the integers from the
* set { 0, 1, ..., n-1 } where n is the length of the permutation.
* The behavior of the Permutation object may become unstable otherwise.
*
* @param p Permutation object to change.
* @param permutation An array of int values, assumed the be a valid permutation
* of the integers from 0 to n-1.
*/
protected final void set(Permutation p, int[] permutation) {
System.arraycopy(permutation, 0, p.permutation, 0, permutation.length);
}

/**
* Changes the integer in one specific location of a Permutation. Individual calls
* to this method will, in most cases, produce an invalid Permutation. The caller
* is responsible for making a combination of calls to this method that together produce
* a valid Permutation. The behavior of the Permutation object may become unstable otherwise.
* The caller should not return until the state of the Permutation object is again valid.
*
* @param p Permutation object to change.
* @param index The index of the position to change.
* @param value The value to change that position to.
*/
protected final void set(Permutation p, int index, int value) {
p.permutation[index] = value;
}

/**
* Changes a range of permutation elements. This method does not verify that the
* change produces a valid permutation. The caller is responsible for making a combination
* of calls to this method and/or the other methods of the Permutation.Mechanic class that
* together produce a valid Permutation.
* The behavior of the Permutation object may become unstable otherwise.
* The caller should not return until the state of the Permutation object is again valid.
*
* @param p Permutation object to change.
* @param index The index for the start of the new elements.
* @param subpermutation The new elements, which are copied into the permutation beginning
* at position index of the permutation.
*/
protected final void set(Permutation p, int index, int[] subpermutation) {
System.arraycopy(subpermutation, 0, p.permutation, index, subpermutation.length);
}

/**
* Changes a range of permutation elements. This method does not verify that the
* change produces a valid permutation. The caller is responsible for making a combination
* of calls to this method and/or the other methods of the Permutation.Mechanic class that
* together produce a valid Permutation.
* The behavior of the Permutation object may become unstable otherwise.
* The caller should not return until the state of the Permutation object is again valid.
*
* @param p Permutation object to change.
* @param source An array to copy elements from.
* @param fromIndex An index into source where copying begins, e.g., the first element
* copied is source[fromIndex].
* @param toIndex An index into the Permutation p, where the elements will be copied to.
* @param numElementsToSet The number of elements to copy from source to p.
*/
protected final void set(Permutation p, int[] source, int fromIndex, int toIndex, int numElementsToSet) {
System.arraycopy(source, fromIndex, p.permutation, toIndex, numElementsToSet);
}
}
}
100 changes: 0 additions & 100 deletions src/test/java/org/cicirello/permutations/PermutationTestCases.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -257,106 +257,6 @@ public void testPermutationSetFromArray() {
);
}

@Test @SuppressWarnings("deprecation") public void testPermutationMechanicSet() {

class MyMech extends Permutation.Mechanic {
public void testSet(Permutation p, int[] a) {
set(p, a);
}
public void testSet(Permutation p, int i, int v) {
set(p, i, v);
}
public void testSet(Permutation p, int i, int[] a) {
set(p, i, a);
}
public void testSet(Permutation p, int[] s, int from, int to, int numElements) {
set(p, s, from, to, numElements);
}
}
MyMech test = new MyMech();

int[][] arrays = { { 0 }, { 1, 0 }, { 1, 0, 2 }, { 3, 1, 2, 0 } };
for (int[] a : arrays) {
Permutation p = new Permutation(a.length, 0);
test.testSet(p, a.clone());
validatePermutation(p, a.length);
for (int i = 0; i < a.length; i++) {
assertEquals(a[i], p.get(i));
}
}
for (int[] a : arrays) {
Permutation p = new Permutation(a.length, 0);
for (int i = 0; i < a.length; i++) {
test.testSet(p, i, a[i]);
}
validatePermutation(p, a.length);
for (int i = 0; i < a.length; i++) {
assertEquals(a[i], p.get(i));
}
}
for (int[] a : arrays) {
Permutation p = new Permutation(a.length, 0);
test.testSet(p, 0, a.clone());
validatePermutation(p, a.length);
for (int i = 0; i < a.length; i++) {
assertEquals(a[i], p.get(i));
}
}
for (int[] a : arrays) {
Permutation p = new Permutation(a);
int[] change = a.length > 2 ? new int[] {7, 5} : new int[] {7};
int start = a.length > 1 ? 1 : 0;
test.testSet(p, start, change);
for (int i = 0; i < start; i++) {
assertEquals(a[i], p.get(i));
}
for (int i = 0; i < change.length; i++) {
assertEquals(change[i], p.get(start+i), "checking changed elements");
}
for (int i = start + change.length; i < a.length; i++) {
assertEquals(a[i], p.get(i));
}
}
for (int[] a : arrays) {
Permutation p = new Permutation(a.length, 0);
test.testSet(p, a.clone(), 0, 0, a.length);
validatePermutation(p, a.length);
for (int i = 0; i < a.length; i++) {
assertEquals(a[i], p.get(i));
}
}
for (int[] a : arrays) {
Permutation p = new Permutation(a);
int[] change = a.length > 2 ? new int[] {7, 5} : new int[] {7};
int start = a.length > 1 ? 1 : 0;
test.testSet(p, change, 0, start, change.length);
for (int i = 0; i < start; i++) {
assertEquals(a[i], p.get(i));
}
for (int i = 0; i < change.length; i++) {
assertEquals(change[i], p.get(start+i), "checking changed elements");
}
for (int i = start + change.length; i < a.length; i++) {
assertEquals(a[i], p.get(i));
}
}
for (int[] a : arrays) {
Permutation p = new Permutation(a);
int[] change = a.length > 2 ? new int[] {9, 9, 7, 5, 9, 9} : new int[] {9, 9, 7, 9, 9};
int start = a.length > 1 ? 1 : 0;
test.testSet(p, change, 2, start, change.length - 4);
for (int i = 0; i < start; i++) {
assertEquals(a[i], p.get(i));
}
for (int i = 2; i < change.length-2; i++) {
assertEquals(change[i], p.get(start+i-2), "checking changed elements");
}
for (int i = start + change.length - 4; i < a.length; i++) {
assertEquals(a[i], p.get(i));
}
}
}

@Test
public void testPermutationCopyConstructor() {
for (int n = 1; n <= 10; n++) {
Expand Down