Permutation (JavaPermutationTools - A Java API for computation on permutations)

java.lang.Object
- org.cicirello.permutations.Permutation

All Implemented Interfaces:

Serializable, Iterable<Permutation>, Copyable<Permutation>
```
public final class Permutation
extends Object
implements Serializable, Iterable<Permutation>, Copyable<Permutation>
```
Representation of a permutation of the integers from 0 to N-1, inclusive. This class provides the functionality to generate random permutations, and to manipulate permutations in a variety of ways.

Since:

1.0

See Also:

Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`Permutation.Mechanic` The Permutation.Mechanic class provides a means of adding application-specific operations on Permutations without the need to directly alter the Permutation class.

Constructor Summary

Constructors
Constructor and Description
`Permutation(int n)` Initializes a random permutation of n integers.
`Permutation(int[] p)` Initializes a permutation of n integers to be identical to the elements of an array.
`Permutation(int n, BigInteger value)` Initializes a specific permutation from an integer in mixed radix form representing the chosen permutation.
`Permutation(int n, int value)` Initializes a specific permutation from an integer in mixed radix form representing the chosen permutation.
`Permutation(int n, Random r)` Initializes a random permutation of n integers.
`Permutation(int n, SplittableRandom r)` Initializes a random permutation of n integers.
`Permutation(Permutation p)` Initializes a permutation of n integers to be identical to a given permutation.
`Permutation(Permutation p, int length)` Initializes a permutation of the integers in the interval [0, length) based on their relative order in a permutation p.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Permutation`	`copy()` Creates an identical copy of this object.
`boolean`	`equals(Object other)` Equality test: Two permutations are equal if they are of the same length and contain the same elements in the same order.
`int`	`get(int i)` Retrieves the i'th integer of the permutation.
`int[]`	`get(int i, int j)` Retrieves a range of elements from the permutation.
`int[]`	`get(int i, int j, int[] array)` Retrieves a range of elements from the permutation.
`int[]`	`getInverse()` Computes the inverse of the permutation.
`Permutation`	`getInversePermutation()` Computes a Permutation that is the inverse of this Permutation.
`int`	`hashCode()` Uses Java's Arrays class's method for generating a hashCode from an array of ints.
`void`	`invert()` Inverts the Permutation, such that if p1 is the Permutation immediately prior to the call to invert, and if p2 is the Permutation immediately after the call to invert, then p1.get(i) == j iff p2.get(j) == i, for all i, j.
`Iterator<Permutation>`	`iterator()` Returns an Iterator over all Permutations the length of this Permutation.
`int`	`length()` Retrieves the length of the permutation.
`void`	`removeAndInsert(int i, int j)` Removes integer from one position and then inserts it into a a new position shifting the rest of the permutation as necessary.
`void`	`removeAndInsert(int i, int size, int j)` Removes a sub-array of integers from one position and then inserts it into a a new position shifting the rest of the permutation as necessary.
`void`	`reverse()` Reverses the order of the elements in the permutation.
`void`	`reverse(int i, int j)` Reverses the order of the elements of a subrange of the permutation.
`void`	`rotate(int numPositions)` Circular rotation of permutation (to the left).
`void`	`scramble()` Randomly shuffles the permutation.
`void`	`scramble(boolean guaranteeDifferent)` Randomly shuffles the permutation.
`void`	`scramble(int i, int j)` Randomly shuffles a segment.
`void`	`scramble(int i, int j, Random r)` Randomly shuffles a segment.
`void`	`scramble(int i, int j, SplittableRandom r)` Randomly shuffles a segment.
`void`	`scramble(Random r)` Randomly shuffles the permutation.
`void`	`scramble(Random r, boolean guaranteeDifferent)` Randomly shuffles the permutation.
`void`	`scramble(SplittableRandom r)` Randomly shuffles the permutation.
`void`	`scramble(SplittableRandom r, boolean guaranteeDifferent)` Randomly shuffles the permutation.
`void`	`set(int[] p)` Changes the state of this permutation to be identical to the elements of an array.
`void`	`swap(int i, int j)` Swaps 2 integers in the permutation.
`void`	`swapBlocks(int a, int b, int i, int j)` Swaps 2 non-overlapping blocks, where a block is a subsequence.
`int[]`	`toArray()` Generates an array of int values from the interval [0, n) in the same order that they occur in this Permutation.
`int[]`	`toArray(int[] array)` Generates an array of int values from the interval [0, n) in the same order that they occur in this Permutation.
`BigInteger`	`toBigInteger()` Generates a unique integer representing the permutation.
`int`	`toInteger()` Generates a unique integer representing the permutation.
`String`	`toString()` Creates a String representing the permutation.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable
forEach, spliterator

- Constructor Detail
  - Permutation
```
public Permutation(int n)
```
    Initializes a random permutation of n integers. Uses java.util.concurrent.ThreadLocalRandom as the source of efficient random number generation.
    
    Parameters:
    
    n - the length of the permutation
  - Permutation
```
public Permutation(int n,
                   SplittableRandom r)
```
    Initializes a random permutation of n integers.
    
    Parameters:
    
    n - the length of the permutation
    
    r - A source of randomness.
  - Permutation
```
public Permutation(int n,
                   Random r)
```
    Initializes a random permutation of n integers.
    
    Parameters:
    
    n - the length of the permutation
    
    r - A source of randomness.
  - Permutation
```
public Permutation(int n,
                   int value)
```
    Initializes a specific permutation from an integer in mixed radix form representing the chosen permutation. See the toInteger() method which can be used to generate this value for a given permutation. The n! permutations of the integers from 0 to n-1 are mapped to the integers from 0..(n!-1). Runtime of this constructor is O(n^2).
    
    Parameters:
    
    n - The length of the permutation.
    
    value - The integer value of the permutation in the interval: 0..(n!-1).
  - Permutation
```
public Permutation(int n,
                   BigInteger value)
```
    Initializes a specific permutation from an integer in mixed radix form representing the chosen permutation. See the toInteger() method which can be used to generate this value for a given permutation. The n! permutations of the integers from 0 to n-1 are mapped to the integers from 0..(n!-1). Runtime of this constructor is O(n^2).
    
    Even with the operations on BigInteger objects, the runtime is O(n^2). It performs O(n^2) operations on primitive values. It performs only O(n) divisions on BigInteger objects. It can be shown that the amortized cost of all of those divisions is bounded by the most costly division (each division involves progressively smaller numbers). The largest number involved in a division is the parameter value, which can be at most n!. The number n! consists of O(log((n-1)!)) = O(n log n) digits. Java's BigInteger division method currently implements the Burnikel-Ziegler algorithm, using the Toom–Cook multiplication algorithm. Dividing m-digit numbers with this combination has a runtime of O(m^1.465 log(m)). Substituting the number of digits for m, we have: O(n^1.465 log(n)^2.465). The cost of all of the divisions is thus less asymptotically than the cost of the primitive operations: O(n^2).
    
    Parameters:
    
    n - The length of the permutation.
    
    value - The integer value of the permutation in the interval: 0..(n!-1).
    
    Since:
    
    1.2.5
  - Permutation
```
public Permutation(int[] p)
```
    Initializes a permutation of n integers to be identical to the elements of an array.
    
    Parameters:
    
    p - An array of integers. Each of the integers in the interval [0, p.length) must occur exactly one time each.
    
    Throws:
    
    IllegalArgumentException - if p either contains duplicates, or contains any negative elements, or contains any elements equal or greater than p.length.
  - Permutation
```
public Permutation(Permutation p)
```
    Initializes a permutation of n integers to be identical to a given permutation.
    
    Parameters:
    
    p - the given permutation.
  - Permutation
```
public Permutation(Permutation p,
                   int length)
```
    Initializes a permutation of the integers in the interval [0, length) based on their relative order in a permutation p. If length is greater than or equal to p.length, then this constructor generates a copy of p. If length is less than p.length, then the new permutation contains the integers, 0, 1, 2, ..., (length - 1), in the order that those elements appear in p. For example, if p is the permutation [ 5, 3, 7, 2, 6, 1, 0, 8, 4] and if length is 4, this constructor will generate the permutation [3, 2, 1, 0] since 3 appears prior to 2, 2 appears prior to 1, and 1 appears prior to 0 in permutation p.
    
    Parameters:
    
    p - the source permutation.
    
    length - size of new permutation
- Method Detail
  - copy
```
public Permutation copy()
```
    Description copied from interface: Copyable
    
    Creates an identical copy of this object.
    
    Specified by:
    
    copy in interface Copyable<Permutation>
    
    Returns:
    
    an identical copy of this object.
  - toInteger
```
public int toInteger()
```
    Generates a unique integer representing the permutation. Maps the permutations of the integers, 0..(N-1), to the integers, 0..(N!-1), using a mixed radix representation. This method is only supported for permutations of length 12 or less. Runtime of this method is O(N^2).
    
    Returns:
    
    a mixed radix representation of the permutation
    
    Throws:
    
    UnsupportedOperationException - when permutation length is greater than 12.
  - toBigInteger
```
public BigInteger toBigInteger()
```
    Generates a unique integer representing the permutation. Maps the permutations of the integers, 0..(N-1), to the integers, 0..(N!-1), using a mixed radix representation.
    
    Even with the use of BigInteger objects, the runtime of this method is O(N^2). Specifically, it performs O(N^2) operations on primitives. And the sequence of operations on BigIntegers costs no more than the cost to compute N! using BigInteger objects, whose runtime bounded by that of the last multiplication of N * (N-1)! The number (N-1)! consists of O(log((N-1)!)) = O(N log N) digits. Java's BigInteger.multiply currently implements the Toom–Cook algorithm, which has a runtime for M-digit numbers of O(M^1.465). Thus, the cost of all of the BigInteger operations is O(N^1.465 log(N)^1.465). Therefore, the runtime is dominated by the cost of the primitive operations: O(N^2).
    
    Returns:
    
    a mixed radix representation of the permutation
    
    Since:
    
    1.2.5
  - getInverse
```
public int[] getInverse()
```
    Computes the inverse of the permutation.
    
    Returns:
    
    The inverse of the permutation, such that for all i, if pi(i) = j, then inv(j) = i
  - getInversePermutation
```
public Permutation getInversePermutation()
```
    Computes a Permutation that is the inverse of this Permutation. Specifically, this.get(i) == j iff inverse.get(j) == i.
    
    Returns:
    
    The inverse of the permutation, such that for all i, this.get(i) == j iff inverse.get(j) == i.
    
    Since:
    
    1.3
  - invert
```
public void invert()
```
    Inverts the Permutation, such that if p1 is the Permutation immediately prior to the call to invert, and if p2 is the Permutation immediately after the call to invert, then p1.get(i) == j iff p2.get(j) == i, for all i, j.
    
    Since:
    
    1.3
  - scramble
```
public void scramble()
```
    Randomly shuffles the permutation. Uses java.util.concurrent.ThreadLocalRandom as the source of efficient random number generation.
  - scramble
```
public void scramble(Random r)
```
    Randomly shuffles the permutation.
    
    Parameters:
    
    r - a source of randomness.
  - scramble
```
public void scramble(SplittableRandom r)
```
    Randomly shuffles the permutation.
    
    Parameters:
    
    r - a source of randomness.
  - scramble
```
public void scramble(boolean guaranteeDifferent)
```
    Randomly shuffles the permutation. Uses java.util.concurrent.ThreadLocalRandom as the source of efficient random number generation.
    
    Parameters:
    
    guaranteeDifferent - if true and if permutation length is at least 2, then method guarantees that the result is a different permutation than it was originally.
    
    Since:
    
    1.4
  - scramble
```
public void scramble(Random r,
                     boolean guaranteeDifferent)
```
    Randomly shuffles the permutation.
    
    Parameters:
    
    r - a source of randomness.
    
    guaranteeDifferent - if true and if permutation length is at least 2, then method guarantees that the result is a different permutation than it was originally.
    
    Since:
    
    1.4
  - scramble
```
public void scramble(SplittableRandom r,
                     boolean guaranteeDifferent)
```
    Randomly shuffles the permutation.
    
    Parameters:
    
    r - a source of randomness.
    
    guaranteeDifferent - if true and if permutation length is at least 2, then method guarantees that the result is a different permutation than it was originally.
    
    Since:
    
    1.4
  - scramble
```
public void scramble(int i,
                     int j)
```
    Randomly shuffles a segment. Uses java.util.concurrent.ThreadLocalRandom as the source of efficient random number generation.
    
    Parameters:
    
    i - endpoint of the segment (precondition: 0 ≤ i < length())
    
    j - endpoint of the segment (precondition: 0 ≤ j < length())
    
    Throws:
    
    ArrayIndexOutOfBoundsException - if either i or j are negative, or if either i or j are greater than or equal to length()
  - scramble
```
public void scramble(int i,
                     int j,
                     Random r)
```
    Randomly shuffles a segment.
    
    Parameters:
    
    i - endpoint of the segment (precondition: 0 ≤ i < length())
    
    j - endpoint of the segment (precondition: 0 ≤ j < length())
    
    r - source of randomness
    
    Throws:
    
    ArrayIndexOutOfBoundsException - if either i or j are negative, or if either i or j are greater than or equal to length()
  - scramble
```
public void scramble(int i,
                     int j,
                     SplittableRandom r)
```
    Randomly shuffles a segment.
    
    Parameters:
    
    i - endpoint of the segment (precondition: 0 ≤ i < length())
    
    j - endpoint of the segment (precondition: 0 ≤ j < length())
    
    r - source of randomness
    
    Throws:
    
    ArrayIndexOutOfBoundsException - if either i or j are negative, or if either i or j are greater than or equal to length()
  - get
```
public int get(int i)
```
    Retrieves the i'th integer of the permutation.
    
    Parameters:
    
    i - the index of the integer to retrieve. (precondition: 0 ≤ i < length())
    
    Returns:
    
    the integer in the i'th position.
    
    Throws:
    
    ArrayIndexOutOfBoundsException - if i is negative, or if i is greater than or equal to length()
  - get
```
public int[] get(int i,
                 int j)
```
    Retrieves a range of elements from the permutation.
    
    Parameters:
    
    i - The starting index.
    
    j - The ending index (inclusive).
    
    Returns:
    
    An array containing the permutation elements from positions i through j, inclusive.
    
    Throws:
    
    IllegalArgumentException - if j < i
    
    IndexOutOfBoundsException - if i is negative, or j ≥ Permutation.length()
    
    Since:
    
    2.0
  - get
```
public int[] get(int i,
                 int j,
                 int[] array)
```
    Retrieves a range of elements from the permutation.
    
    Parameters:
    
    i - The starting index.
    
    j - The ending index (inclusive).
    
    array - An array to hold the result. If the array is null or if its length is not equal to the number of retrieved elements, then a new array is constructed.
    
    Returns:
    
    The array containing the permutation elements from positions i through j, inclusive.
    
    Throws:
    
    IllegalArgumentException - if j < i
    
    IndexOutOfBoundsException - if i is negative, or j ≥ Permutation.length()
    
    Since:
    
    2.0
  - toArray
```
public int[] toArray()
```
    Generates an array of int values from the interval [0, n) in the same order that they occur in this Permutation. The array that is returned is independent of the object state (i.e., changes to its contents will not affect the Permutation).
    
    Returns:
    
    an int array containing the Permutation elements in the same order that they appear in the Permutation.
    
    Since:
    
    1.3
  - toArray
```
public int[] toArray(int[] array)
```
    Generates an array of int values from the interval [0, n) in the same order that they occur in this Permutation. The array that is returned is independent of the object state (i.e., changes to its contents will not affect the Permutation).
    
    Parameters:
    
    array - An array to hold the result. If array is null or if array.length is not equal to the length of the permutation, then this method will construct a new array for the result.
    
    Returns:
    
    an int array containing the Permutation elements in the same order that they appear in the Permutation.
    
    Since:
    
    1.5
  - length
```
public int length()
```
    Retrieves the length of the permutation.
    
    Returns:
    
    length of the permutation
  - swap
```
public void swap(int i,
                 int j)
```
    Swaps 2 integers in the permutation.
    
    Parameters:
    
    i - position of first to swap (precondition: 0 ≤ i < length() ∧ i != j)
    
    j - the position of the second to swap (precondition: 0 ≤ j < length() ∧ i != j)
    
    Throws:
    
    ArrayIndexOutOfBoundsException - if either i or j are negative, or if either i or j are greater than or equal to length()
  - swapBlocks
```
public void swapBlocks(int a,
                       int b,
                       int i,
                       int j)
```
    Swaps 2 non-overlapping blocks, where a block is a subsequence.
    
    Parameters:
    
    a - Starting index of first block.
    
    b - Ending index, inclusive, of first block.
    
    i - Starting index of second block.
    
    j - Ending index, inclusive, of second block.
    
    Throws:
    
    IllegalArgumentException - if the following constraint is violated: 0 ≤ a ≤ b < i ≤ j < length().
    
    Since:
    
    2.0
  - reverse
```
public void reverse()
```
    Reverses the order of the elements in the permutation.
  - reverse
```
public void reverse(int i,
                    int j)
```
    Reverses the order of the elements of a subrange of the permutation.
    
    Parameters:
    
    i - position of first index (precondition: 0 ≤ i < length() ∧ i != j)
    
    j - the position of the second index (precondition: 0 ≤ j < length() ∧ i != j)
    
    Throws:
    
    ArrayIndexOutOfBoundsException - if either i or j are negative, or if either i or j are greater than or equal to length()
  - removeAndInsert
```
public void removeAndInsert(int i,
                            int j)
```
    Removes integer from one position and then inserts it into a a new position shifting the rest of the permutation as necessary.
    
    Parameters:
    
    i - position of integer to remove and insert (precondition: 0 ≤ i < length())
    
    j - the position of the insertion point (precondition: 0 ≤ j < length())
    
    Throws:
    
    ArrayIndexOutOfBoundsException - if either i or j are negative, or if either i or j are greater than or equal to length()
  - rotate
```
public void rotate(int numPositions)
```
    Circular rotation of permutation (to the left).
    
    Parameters:
    
    numPositions - Number of positions to rotate.
  - removeAndInsert
```
public void removeAndInsert(int i,
                            int size,
                            int j)
```
    Removes a sub-array of integers from one position and then inserts it into a a new position shifting the rest of the permutation as necessary.
    
    Parameters:
    
    i - position of first integer in sub-array to remove and insert (precondition: 0 ≤ i < length())
    
    size - the length of the sub-array (precondition: size + i < length() and size + j - 1 < length())
    
    j - the position of the insertion point (precondition: 0 ≤ j < length())
    
    Throws:
    
    ArrayIndexOutOfBoundsException - if either i or j are negative, or if either i or j are greater than or equal to length().
  - set
```
public void set(int[] p)
```
    Changes the state of this permutation to be identical to the elements of an array.
    
    Parameters:
    
    p - An array of integers. Each of the integers in the interval [0, p.length) must occur exactly one time each.
    
    Throws:
    
    IllegalArgumentException - if p either contains duplicates, or contains any negative elements, or contains any elements equal or greater than p.length.
    
    Since:
    
    1.2.5
  - iterator
```
public Iterator<Permutation> iterator()
```
    Returns an Iterator over all Permutations the length of this Permutation. Iteration begins at this Permutation. This Iterator does not iterate over the integers within the Permutation. If you do need to iterate over all permutations of a given length, then this method is much more efficient than using the Permutation(int,int) constructor repeatedly incrementing the value passed for the second parameter.
    
    Specified by:
    
    iterator in interface Iterable<Permutation>
    
    Returns:
    
    an Iterator
    
    Since:
    
    1.2
  - toString
```
public String toString()
```
    Creates a String representing the permutation.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    a space separated sequence of the permutation's elements
  - equals
```
public boolean equals(Object other)
```
    Equality test: Two permutations are equal if they are of the same length and contain the same elements in the same order.
    
    Overrides:
    
    equals in class Object
    
    Parameters:
    
    other - the permutation to which to compare
    
    Returns:
    
    true if this is equal to other, and false otherwise
  - hashCode
```
public int hashCode()
```
    Uses Java's Arrays class's method for generating a hashCode from an array of ints.
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
    
    a hashCode for the permutation

Class Permutation

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.Iterable

Constructor Detail

Permutation

Permutation

Permutation

Permutation

Permutation

Permutation

Permutation

Permutation

Method Detail

copy

toInteger

toBigInteger

getInverse

getInversePermutation

invert

scramble

scramble

scramble

scramble

scramble

scramble

scramble

scramble

scramble

get

get

get

toArray

toArray

length

swap

swapBlocks

reverse

reverse

removeAndInsert

rotate

removeAndInsert

set

iterator

toString

equals

hashCode