Class Permutation.Mechanic

  • Enclosing class:
    Permutation

    public static class Permutation.Mechanic
    extends Object

    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.

    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.

    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.

    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.

    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.

    • Constructor Detail

      • Mechanic

        protected Mechanic()
        The default constructor can only be called by subclasses.
    • Method Detail

      • set

        protected final void set​(Permutation p,
                                 int[] permutation)
        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.
        Parameters:
        p - Permutation object to change.
        permutation - An array of int values, assumed the be a valid permutation of the integers from 0 to n-1.
      • set

        protected final void set​(Permutation p,
                                 int index,
                                 int value)
        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.
        Parameters:
        p - Permutation object to change.
        index - The index of the position to change.
        value - The value to change that position to.
      • set

        protected final void set​(Permutation p,
                                 int index,
                                 int[] subpermutation)
        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.
        Parameters:
        p - Permutation object to change.
        index - The index for the start of the new elements.
        subpermutation - The new elements, which are copied into the permutation beginning at position index of the permutation.