PermutationGenerator (Uncommons Maths 1.2.3 API)

java.lang.Object
- org.uncommons.maths.combinatorics.PermutationGenerator<T>

Type Parameters:

T - The type of element that the permutation will consist of.

All Implemented Interfaces:

Iterable<List<T>>
```
public class PermutationGenerator<T>
extends Object
implements Iterable<List<T>>
```
Permutation generator for generating all permutations for all sets up to 20 elements in size. While 20 may seem a low limit, bear in mind that the number of permutations of a set of size n is n! For a set of 21 items, the number of permutations is bigger than can be stored in Java's 64-bit long integer data type. Therefore it seems unlikely that you could ever generate, let alone process, all of the permutations in a reasonable time frame. For this reason the implementation is optimised for sets of size 20 or less (this affords better performance by allowing primitive numeric types to be used for calculations rather than BigInteger).

Author:

Daniel Dyer (modified from the original version written by Michael Gilleland of Merriam Park Software - http://www.merriampark.com/perm.htm).

See Also:

CombinationGenerator

Constructor Summary

Constructors
Constructor and Description
`PermutationGenerator(Collection<T> elements)` Permutation generator that generates all possible orderings of the elements in the specified set.
`PermutationGenerator(T[] elements)` Permutation generator that generates all possible orderings of the elements in the specified set.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`long`	`getRemainingPermutations()` Returns the number of permutations not yet generated.
`long`	`getTotalPermutations()` Returns the total number of unique permutations that can be generated for the given set of elements.
`boolean`	`hasMore()` Are there more permutations that have not yet been returned?
`Iterator<List<T>>`	`iterator()` Provides a read-only iterator for iterating over the permutations generated by this object.
`T[]`	`nextPermutationAsArray()` Generate the next permutation and return an array containing the elements in the appropriate order.
`T[]`	`nextPermutationAsArray(T[] destination)` Generate the next permutation and return an array containing the elements in the appropriate order.
`List<T>`	`nextPermutationAsList()` Generate the next permutation and return a list containing the elements in the appropriate order.
`List<T>`	`nextPermutationAsList(List<T> destination)` Generate the next permutation and return a list containing the elements in the appropriate order.
`void`	`reset()` Resets the generator state.

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

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

- Constructor Detail
  - PermutationGenerator
```
public PermutationGenerator(T[] elements)
```
    Permutation generator that generates all possible orderings of the elements in the specified set.
    
    Parameters:
    
    elements - The elements to permute.
  - PermutationGenerator
```
public PermutationGenerator(Collection<T> elements)
```
    Permutation generator that generates all possible orderings of the elements in the specified set.
    
    Parameters:
    
    elements - The elements to permute.
- Method Detail
  - reset
```
public final void reset()
```
    Resets the generator state.
  - getRemainingPermutations
```
public long getRemainingPermutations()
```
    Returns the number of permutations not yet generated.
    
    Returns:
    
    The number of unique permutations still to be generated.
  - getTotalPermutations
```
public long getTotalPermutations()
```
    Returns the total number of unique permutations that can be generated for the given set of elements.
    
    Returns:
    
    The total number of permutations.
  - hasMore
```
public boolean hasMore()
```
    Are there more permutations that have not yet been returned?
    
    Returns:
    
    true if there are more permutations, false otherwise.
  - nextPermutationAsArray
```
public T[] nextPermutationAsArray()
```
    Generate the next permutation and return an array containing the elements in the appropriate order.
    
    Returns:
    
    The next permutation as an array.
    
    See Also:
    
    nextPermutationAsArray(Object[]), nextPermutationAsList()
  - nextPermutationAsArray
```
public T[] nextPermutationAsArray(T[] destination)
```
    Generate the next permutation and return an array containing the elements in the appropriate order. This overloaded method allows the caller to provide an array that will be used and returned. The purpose of this is to improve performance when iterating over permutations. If the nextPermutationAsArray() method is used it will create a new array every time. When iterating over permutations this will result in lots of short-lived objects that have to be garbage collected. This method allows a single array instance to be reused in such circumstances.
    
    Parameters:
    
    destination - Provides an array to use to create the permutation. The specified array must be the same length as a permutation. This is the array that will be returned, once it has been filled with the elements in the appropriate order.
    
    Returns:
    
    The next permutation as an array.
  - nextPermutationAsList
```
public List<T> nextPermutationAsList()
```
    Generate the next permutation and return a list containing the elements in the appropriate order.
    
    Returns:
    
    The next permutation as a list.
    
    See Also:
    
    nextPermutationAsList(java.util.List), nextPermutationAsArray()
  - nextPermutationAsList
```
public List<T> nextPermutationAsList(List<T> destination)
```
    Generate the next permutation and return a list containing the elements in the appropriate order. This overloaded method allows the caller to provide a list that will be used and returned. The purpose of this is to improve performance when iterating over permutations. If the nextPermutationAsList() method is used it will create a new list every time. When iterating over permutations this will result in lots of short-lived objects that have to be garbage collected. This method allows a single list instance to be reused in such circumstances.
    
    Parameters:
    
    destination - Provides a list to use to create the permutation. This is the list that will be returned, once it has been filled with the elements in the appropriate order.
    
    Returns:
    
    The next permutation as a list.
  - iterator
```
public Iterator<List<T>> iterator()
```
    Provides a read-only iterator for iterating over the permutations generated by this object. This method is the implementation of the Iterable interface that permits instances of this class to be used with the new-style for loop.
    
    For example:
```
 List<Integer> elements = Arrays.asList(1, 2, 3);
 PermutationGenerator<Integer> permutations = new PermutationGenerator(elements);
 for (List<Integer> p : permutations)
 {
     // Do something with each permutation.
 }
 
```
    Specified by:
    
    iterator in interface Iterable<List<T>>
    
    Returns:
    
    An iterator.
    
    Since:
    
    1.1

Class PermutationGenerator<T>

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.Iterable

Constructor Detail

PermutationGenerator

PermutationGenerator

Method Detail

reset

getRemainingPermutations

getTotalPermutations

hasMore

nextPermutationAsArray

nextPermutationAsArray

nextPermutationAsList

nextPermutationAsList

iterator