Package squidpony.squidmath

Class CombinationGenerator<T>

java.lang.Object
squidpony.squidmath.CombinationGenerator<T>
Type Parameters:
T - The type of element that the combinations are made from.
All Implemented Interfaces:
Serializable, Iterable<List<T>>
public class CombinationGenerator<T>
extends Object
implements Iterable<List<T>>, Serializable
Combination generator for generating all combinations of a given size from the specified set of elements. For performance reasons, this implementation is restricted to operating with set sizes and combination lengths that produce no more than 2^63 different combinations.
Originally part of the Uncommon Maths software package.
Author:
Daniel Dyer (modified from the original version written by Michael Gilleland of Merriam Park Software - http://www.merriampark.com/comb.htm).
See Also:
PermutationGenerator, Serialized Form

  • Constructor Details

    • CombinationGenerator

      public CombinationGenerator​(T[] elements, int combinationLength)
      Create a combination generator that generates all combinations of a specified length from the given set.
      Parameters:
      elements - The set from which to generate combinations; will be used directly (not copied)
      combinationLength - The length of the combinations to be generated.

    • CombinationGenerator

      public CombinationGenerator​(Collection<T> elements, int combinationLength, T[] filler)
      Create a combination generator that generates all combinations of a specified length from the given set.
      Parameters:
      elements - The set from which to generate combinations.
      combinationLength - The length of the combinations to be generated.
      filler - An array of T with the same length as elements or less (often 0); needed because GWT can't create a generic array. If elements is not a Collection defined in the JDK (by GWT), then this should have exactly the same length as elements, since GWT can create larger versions of an array on its own, but our code can't easily.

  • Method Details

    • reset

      public final void reset()
      Reset the combination generator.

    • getRemainingCombinations

      public long getRemainingCombinations()
      Returns:
      The number of combinations not yet generated.

    • hasMore

      public boolean hasMore()
      Are there more combinations?
      Returns:
      true if there are more combinations available, false otherwise.

    • getTotalCombinations

      public long getTotalCombinations()
      Returns:
      The total number of combinations.

    • nextCombinationAsArray

      public T[] nextCombinationAsArray​(T[] destination)
      Generate the next combination and return an array containing the appropriate elements. 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 combinations. This method allows a single array instance to be reused.
      Parameters:
      destination - Provides an array to use to create the combination. The specified array must be the same length as a combination.
      Returns:
      The provided array now containing the elements of the combination.

    • nextCombinationAsList

      public List<T> nextCombinationAsList()
      Generate the next combination and return a list containing the appropriate elements.
      Returns:
      A list containing the elements that make up the next combination.
      See Also:
      nextCombinationAsList(List)

    • nextCombinationAsList

      public List<T> nextCombinationAsList​(List<T> destination)
      Generate the next combination and return a list containing the appropriate elements. 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 combinations. If the nextCombinationAsList() method is used it will create a new list every time. When iterating over combinations 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 combination.
      Returns:
      The provided list now containing the elements of the combination.

    • iterator

      public Iterator<List<T>> iterator()

      Provides a read-only iterator for iterating over the combinations 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);
 CombinationGenerator<Integer> combinations = new CombinationGenerator(elements, 2);
 for (List<Integer> c : combinations)
 {
     // Do something with each combination.
 }
      Specified by:
      iterator in interface Iterable<T>
      Returns:
      An iterator.
      Since:
      1.1