de.caff.generics.util.combi

## Class Combinations<T>

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

- Type Parameters:
    `T` - element type of the incoming set
  All Implemented Interfaces:
    java.lang.Iterable<Indexable<T>>

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

  Create all combinations. This class takes care of creating all combination of n choose k lazily from a given set of objects.

  Combinations returned will be ordered when considering the index into the incoming elements:

  - Each single combination will appear in the order of the incoming elements. i.e. the each element has in the base set is ascending.
  - Steps will be ordered lexicographic by their indexes into the incoming elements when viewed inverted (from end to start). I.e. a choice of 2 from the string `"ABCD"` will return
    - `"AB"`
    - `"AC"`
    - `"BC"`
    - `"AD"`
    - `"BD"`
    - `"CD"`
    When you read each result from right to left they are in strict lexical order.
  There are various subclasses which take care of combinations of primitive values avoiding boxing and unboxing overhead:
  - `Combinations.OfRange` is the most basic and takes care of combinations of consecutive indices. Indeed all other combinations classes are based on `createRangeIterator(int, int)` which is used without overhead only by `OfRange`.
  - `Combinations.OfInt` handle combinations of arbitrary `int` values.
  - `Combinations.OfLong` handles combinations of arbitrary `long` values.
  - `Combinations.OfShort` handles combinatons of arbitrary `short` values.
  - `Combinations.OfByte` handles combinations of arbitrary `byte` values.
  - `Combinations.OfDouble` handles combinations of arbitrary `double` values.
  - `Combinations.OfFloat` handles combintaions of arbitrary `float` values.
  - `Combinations.OfChar` handles combinations of arbitrary `char` values.
  - `Combinations.OfString` handles combinations of the characters of a `java.lang.CharSequence`.
  - `Combinations.OfBoolean` handles combintaions of arbitrary `byte` values.
  Since:
    November 18, 2021
  Author:
    Rammi

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Combinations.OfBoolean` Combinations of boolean values.
    `static class` | `Combinations.OfByte` Combinations of byte values.
    `static class` | `Combinations.OfChar` Combinations of char values.
    `static class` | `Combinations.OfDouble` Combinations of double values.
    `static class` | `Combinations.OfFloat` Combinations of float values.
    `static class` | `Combinations.OfInt` The combinations of integer values.
    `static class` | `Combinations.OfLong` Combinations of long values.
    `static class` | `Combinations.OfRange` The combinations of an index range.
    `static class` | `Combinations.OfShort` Combinations of short values.
    `static class` | `Combinations.OfString` The combinations of the characters of a string, as strings.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Combinations(int k, java.util.Collection<T> set)` Constructor.
    `Combinations(int k, Countable<T> set)` Constructor.
    `Combinations(int k, Indexable<T> elements)` Constructor.
    `Combinations(int k, java.util.List<T> list)` Constructor.
    `Combinations(int k, T... elems)` Constructor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `(package private) static void` | `checkBinomial(int n, int k)` Check the parameters of a "n choice k" for sanity.
    `static java.math.BigInteger` | `count(int n, int k)` Get the number of combinations for n choose k.
    `static java.util.Iterator<IntIndexable>` | `createRangeIterator(int n, int k)` Create an iterator which iterates of the subsets of size `k` from the set `{0, 1, 2, ..., n-1}`.
    `java.util.Iterator<Indexable<T>>` | `iterator()`
    `static void` | `main(java.lang.String[] args)`

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

    - #### Combinations

          public Combinations(int k,
                              @NotNull
                              Indexable<T> elements)

      Constructor.
      Parameters:
        `k` - number of elements to choose, has to be non-negative and not more the size of the `elements` set
        `elements` - set from which elements are chosen

    - #### Combinations

          public Combinations(int k,
                              @NotNull
                              java.util.List<T> list)

      Constructor.
      Parameters:
        `k` - number of elements to choose, has to be non-negative and not more the size of the `list`
        `list` - list from which elements will be cosen

    - #### Combinations

          public Combinations(int k,
                              @NotNull
                              Countable<T> set)

      Constructor.
      Parameters:
        `k` - number of elements to choose, has to be non-negative and not more the size of the `set`
        `set` - set from which elements will be chosen

    - #### Combinations

          public Combinations(int k,
                              @NotNull
                              java.util.Collection<T> set)

      Constructor.
      Parameters:
        `k` - number of elements to choose, has to be non-negative and not more the size of the `set`
        `set` - set from which elements will be chosen

    - #### Combinations

          @SafeVarargs
          public Combinations(int k,
                                           @NotNull
                                           T... elems)

      Constructor.
      Parameters:
        `k` - number of elements to choose, has to be non-negative and not more the number of `elements`
        `elems` - set from which elements will be chosen

  - ### Method Detail

    - #### iterator

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

      Specified by:
        `iterator` in interface `java.lang.Iterable<Indexable<T>>`

    - #### createRangeIterator

          @NotNull
          public static java.util.Iterator<IntIndexable> createRangeIterator(int n,
                                                                                      int k)

      Create an iterator which iterates of the subsets of size `k` from the set `{0, 1, 2, ..., n-1}`.

      As the latter can be used as indices this iterator can be used as a base for chosing from any set.

      Parameters:
        `n` - number of elements in the set from which is chosen
        `k` - number of elements in the chosen sub sets
      Returns:
        iterator which returns one possible choice from each set, with ordered numbers

    - #### checkBinomial

          static void checkBinomial(int n,
                                    int k)

      Check the parameters of a "n choice k" for sanity.
      Parameters:
        `n` - n, size of the set from which is chosen
        `k` - k, number of chosen elements
      Throws:
        `java.lang.IllegalArgumentException` - if parameters are invalid

    - #### count

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

      Get the number of combinations for n choose k.
      Parameters:
        `n` - n, size of the set from which is chosen
        `k` - k, number of chosen elements
      Returns:
        number of all possible combinations
      Throws:
        `java.lang.IllegalArgumentException` - if parameters are invalid

    - #### main

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