Merge pull request #217 from cicirello/remove-deprecated

Removed Permutation.Mechanic nested class

Author: cicirello

CHANGELOG.md

@@ -17,6 +17,7 @@ details below.
 ### Deprecated
 
 ### Removed
+* Permutation.Mechanic nested class previously deprecated in v3.2.0 (breaking change).
 
 ### Fixed
 

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

@@ -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);
-		}
-	}
 }

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

@@ -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++) {