de.caff.generics.util.combi

## Class Permutations<T>

- java.lang.Object
- - de.caff.generics.util.combi.Permutations<T>

- Type Parameters:
    `T` - type pf elements which will be permuted
  All Implemented Interfaces:
    java.lang.Iterable<Indexable<T>>

      public class Permutations<T>
      extends java.lang.Object
      implements java.lang.Iterable<Indexable<T>>

  Helper class for permutations.

  This class takes care of permutating a set of generic values. Evaluation is done lazy using the Steinhaus-Johnson-Trotter algorithm. As the number of permutations becomes large very fast, this class does not provide a size which would tell how many elements will be returned from the iterator until it finally stops (obviously `n!` when the number of elements to be rearranged is `n`),

  There are various subclasses which take care of permutations of primitive values avoiding boxing and unboxing overhead:

  - `Permutations.OfRange` is the most basic and takes care of rearranging a range of consecutive indices. Indeed all other permutations are based on `Permutations.RangeIterator` which is used without overhead only by `OfRange`.
  - `Permutations.OfInt` rearranges arbitrary `int` values.
  - `Permutations.OfLong` rearranges arbitrary `long` values.
  - `Permutations.OfShort` rearranges arbitrary `short` values.
  - `Permutations.OfByte` rearranges arbitrary `byte` values.
  - `Permutations.OfDouble` rearranges arbitrary `double` values.
  - `Permutations.OfFloat` rearranges arbitrary `float` values.
  - `Permutations.OfChar` rearranges arbitrary `char` values.
  - `Permutations.OfString` rearranges the characters of a `java.lang.CharSequence`.
  - `Permutations.OfBoolean` rearranges arbitrary `byte` values.
  Since:
    November 17, 2021
  Author:
    Rammi

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Permutations.OfBoolean` The permutations of boolean values.
    `static class` | `Permutations.OfByte` The permutations of byte values.
    `static class` | `Permutations.OfChar` The permutations of char values.
    `static class` | `Permutations.OfDouble` The permutations of double values.
    `static class` | `Permutations.OfFloat` The permutations of float values.
    `static class` | `Permutations.OfInt` The permutations of integer values.
    `static class` | `Permutations.OfLong` The permutations of long values.
    `static class` | `Permutations.OfRange` The permutations of an index range.
    `static class` | `Permutations.OfShort` The permutations of short values.
    `static class` | `Permutations.OfString` The permutations of the characters of a string, as strings.
    `static class` | `Permutations.RangeIterator` Iterator using the Steinhaus-Johnson-Trotter algorithm for an index range.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `(package private) static Indexable<java.math.BigInteger>` | `FIRST_FACTORIALS` Precalculated set of factorials (big int).
    `(package private) static LongIndexable` | `FIRST_FACTORIALS_LONG` Precalculated set of factorials (long).

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Permutations(java.util.Collection<T> set)` Constructor.
    `Permutations(Countable<T> set)` Constructor.
    `Permutations(Indexable<T> set)` Constructor.
    `Permutations(java.util.List<T> list)` Constructor.
    `Permutations(T... elems)` Constructor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static java.math.BigInteger` | `count(int n)` Get the number of permutations for a set of size n.
    `(package private) static java.math.BigInteger` | `factorial(int n)`
    `java.util.Iterator<Indexable<T>>` | `iterator()` Get the iterator which provides the permutations.
    `static void` | `main(java.lang.String[] args)` Test code.

    - ### 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`

- - ### Field Detail

    - #### FIRST_FACTORIALS

          static final Indexable<java.math.BigInteger> FIRST_FACTORIALS

      Precalculated set of factorials (big int).

    - #### FIRST_FACTORIALS_LONG

          static final LongIndexable FIRST_FACTORIALS_LONG

      Precalculated set of factorials (long).

  - ### Constructor Detail

    - #### Permutations

          public Permutations(@NotNull
                              Indexable<T> set)

      Constructor.
      Parameters:
        `set` - elements which will be permuted

    - #### Permutations

          public Permutations(@NotNull
                              java.util.List<T> list)

      Constructor.
      Parameters:
        `list` - elements which will be permuted

    - #### Permutations

          public Permutations(@NotNull
                              Countable<T> set)

      Constructor.
      Parameters:
        `set` - elements which will be permuted

    - #### Permutations

          public Permutations(@NotNull
                              java.util.Collection<T> set)

      Constructor.
      Parameters:
        `set` - elements which will be permuted

    - #### Permutations

          @SafeVarargs
          public Permutations(@NotNull
                                           T... elems)

      Constructor.
      Parameters:
        `elems` - elements which will be permuted

  - ### Method Detail

    - #### iterator

          @NotNull
          public java.util.Iterator<Indexable<T>> iterator()

      Get the iterator which provides the permutations.
      Specified by:
        `iterator` in interface `java.lang.Iterable<Indexable<T>>`
      Returns:
        permutations

    - #### count

          @NotNull
          public static java.math.BigInteger count(int n)

      Get the number of permutations for a set of size n.
      Parameters:
        `n` - set size. at least `0`
      Returns:
        number of permutations, equal to n!

    - #### factorial

          @NotNull
          static java.math.BigInteger factorial(int n)

    - #### main

          public static void main(@NotNull
                                  java.lang.String[] args)

      Test code.
      Parameters:
        `args` - a number