Package: groovy.util

## [Java] Class PermutationGenerator<E>

- groovy.util.PermutationGenerator

- All Implemented Interfaces and Traits:
    Iterator

      public class PermutationGenerator<E>
      extends Object
      implements Iterator

  Systematically generate permutations. Adapted from Java Code by Michael Gilleland (released with no restrictions) using an algorithm described here: Kenneth H. Rosen, Discrete Mathematics and Its Applications, 2nd edition (NY: McGraw-Hill, 1991), pp. 282-284

- - ### Constructor Summary

    Constructors
    Constructor and description
    `PermutationGenerator(Collection<E> items)` WARNING: Don't make n too large.
    `PermutationGenerator(Iterable<E> items)` Creates a generator from the supplied iterable.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public BigInteger` | `getTotal()` Returns the total number of permutations.
    `` | `public boolean` | `hasNext()` Returns `true` if the iteration has more elements. (In other words, returns `true` if next would return an element rather than throwing an exception.) Returns: `true` if the iteration has more elements
    `` | `public List<E>` | `next()` Generate next permutation (algorithm from Rosen p. 284)
    `` | `public void` | `remove()` Removes from the underlying collection the last element returned by this iterator (optional operation). This method can be called only once per call to next. The behavior of an iterator is unspecified if the underlying collection is modified while the iteration is in progress in any way other than by calling this method, unless an overriding class has specified a concurrent modification policy. The behavior of an iterator is unspecified if this method is called after a call to the forEachRemaining method. throws: UnsupportedOperationException if the `remove` operation is not supported by this iterator throws: IllegalStateException if the `next` method has not yet been called, or the `remove` method has already been called after the last call to the `next` method Implementation Requirements: The default implementation throws an instance of UnsupportedOperationException and performs no other action.
    `` | `public void` | `reset()` Resets the generator to its initial state.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### public PermutationGenerator(Collection<E> items)

      WARNING: Don't make n too large. Recall that the number of permutations is n! which can be very large, even when n is as small as 20 -- 20! = 2,432,902,008,176,640,000 and 21! is too big to fit into a Java long, which is why we use BigInteger instead.

      Parameters:
        `items` - the items to permute

    - #### public PermutationGenerator(Iterable<E> items)

      Creates a generator from the supplied iterable.

      Parameters:
        `items` - the items to permute

  - ### Method Detail

    - #### public BigInteger getTotal()

      Returns the total number of permutations.

      Returns:
        the total permutation count

    - #### public boolean hasNext()

      Returns `true` if the iteration has more elements. (In other words, returns `true` if next would return an element rather than throwing an exception.)

      Returns:
        `true` if the iteration has more elements

    - #### public List<E> next()

      Generate next permutation (algorithm from Rosen p. 284)

      Returns:
        the items permuted

    - #### public void remove()

      Removes from the underlying collection the last element returned by this iterator (optional operation). This method can be called only once per call to next.

      The behavior of an iterator is unspecified if the underlying collection is modified while the iteration is in progress in any way other than by calling this method, unless an overriding class has specified a concurrent modification policy.

      The behavior of an iterator is unspecified if this method is called after a call to the forEachRemaining method.

      throws:
        UnsupportedOperationException if the `remove` operation is not supported by this iterator
      throws:
        IllegalStateException if the `next` method has not yet been called, or the `remove` method has already been called after the last call to the `next` method
      Implementation Requirements:
        The default implementation throws an instance of UnsupportedOperationException and performs no other action.

    - #### public void reset()

      Resets the generator to its initial state.