org.paukov.combinatorics.Generator Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of combinatoricslib Show documentation
Very simple java library to generate permutations, combinations and other combinatorial sequences.
The newest version!
/**
 * Combinatorics Library
 * Copyright 2012 Dmytro Paukov [email protected]
 */
package org.paukov.combinatorics;

import java.util.ArrayList;
import java.util.Iterator;
import java.util.List;

/**
 * Abstract base class for all generic generators of the library.
 *
 * This is a library written on Java to resolve some combinatorics issues such
 * as generating combinatorial objects (permutations, partitions, compositions,
 * subsets, combinations and etc).
 *
 * Type of the items should be specified as a parameter of generators and vectors.
 *
 * There is a general pattern how to use the generators:
 *  * // create the initial vector or set
 * ICombinatoricsVector<T> vector = CombinatoricsFactory.createVector(new <T>[]{ elements } );
 *
 * // create a concrete generator
 * Generator<T> generator = CombinatoricsFactory.create<Concrete>Generator(vector);
 *
 * // iterate the generated objects
 * for (ICombinatoricsVector<T> v : generator) {
 * 	System.out.println( v );
 * }
 * 
 *
 * @param  Type of the elements in the generated vectors.
 * @author Dmytro Paukov
 * @version 2.0
 * @see ICombinatoricsVector
 * @see Iterator
 * @see CombinatoricsFactory
 */
public abstract class Generator implements
    IGenerator> {

  /**
   * Creates an iterator for enumerating all generated objects/vectors
   *
   * @return The iterator over the generated objects/vectors
   * @deprecated This method will removed in the near future. Use the method iterator()
   * instead of this method
   */
  @Deprecated
  public Iterator> createIterator() {
    return iterator();
  }

  /**
   * Returns all generated vectors as a list
   *
   * @return List of all generated objects/vectors
   */
  public List> generateAllObjects() {
    return generateFilteredObjects(null);
  }

  /**
   * Returns the generated vectors filtered by a filter
   *
   * @param filter The filter to be applied to the generated result
   * @return The list of the filtered vectors
   */
  public List> generateFilteredObjects(
      IFilter> filter) {
    List> list = new ArrayList<>();
    long index = 0;
    for (ICombinatoricsVector vector : this) {
      if (filter == null || filter.accepted(index, vector)) {
        list.add(vector);
      }
      index++;
    }
    return list;
  }

  /**
   * Returns vectors as a list for specified range of indexes (from the
   * startIndex to stopIndex)
   *
   * @return List of the generated objects/vectors
   */
  public List> generateObjectsRange(long startIndex,
      long stopIndex) {
    assert (startIndex <= stopIndex);
    List> list = new ArrayList<>();
    Iterator> iterator = this.iterator();
    long index = 1;
    while (iterator.hasNext()) {
      if (index >= startIndex && index <= stopIndex) {
        list.add(iterator.next());
      } else if (index > stopIndex) {
        return list;
      } else {
        iterator.next();
      }
      index++;
    }
    return list;
  }

}