beryx / streamplify

Java 8 combinatorics-related streams and other utilities

Streamplify

The goal of this library is to provide useful Java 8 streams and to assist you in building new streams that allow efficient parallel processing.

The utilities offered by Streamplify include:

• combinatorics streams: permutations, combinations, Cartesian products, power sets, derangements, partial permutations.
• classes that help you implement your own efficient parallel streams.

Example

The following code snippet uses a parallel permutation stream to find all solutions of the N-Queens problem for n = 10.

System.out.println(new Permutations(10)
        .parallelStream()
        .filter(perm -> {
            for(int i = 0; i < perm.length - 1; i++) {
                for(int j = i + 1; j < perm.length; j++) {
                    if(Math.abs(perm[j] - perm[i]) == j - i) return false;
                }
            }
            return true;
        })
        .map(perm -> IntStream.range(0, perm.length)
                .mapToObj(i -> "(" + (i + 1) + "," + (perm[i] + 1) + ")")
                .collect(Collectors.joining(", ")))
        .collect(Collectors.joining("\n")));

Before starting to use the library, take a look at the examples, read the documentation and consult the javadoc.

Streamplify is available in Maven Central and JCenter.

Contribute to this project!

We accept all types of contributions and we are very welcoming to first time contributors.

Read how to contribute and jump in!

streamplify's Issues

Add support for partial permutation streams

This is an up-for-grabs issue, so hurry up and grab it!

Your task is to add support for partial permutation streams.
(Note that the term partial permutation is sometimes used to denote k-permutations of n. This issue is NOT about this kind of permutations.)

Consult the implementation of the other combinatorics classes (permutations, combinations, Cartesian product) and structure your code in a similar way:

• put your classes in a package named org.beryx.streamplify.partperm.
• create a subclass of LongIndexedSpliterator called LongPartialPermutations, which can be used for partial permutations with a cardinality that fits in a long (that is, for sets with at most 20 elements).
  Hint: use LongPermutations.java as template for this class.
• create a subclass of BigIntegerIndexedSpliterator called BigIntegerPartialPermutations, which allows partial permutations of virtually any cardinality.
  Hint: use BigIntegerPermutations.java as template for this class.
• create a StreamableProxy calledPartialPermutations, which delegates to either LongPartialPermutations or BigIntegerPartialPermutations.
  Hint: use Permutations.java as template for this class.
• create an abstract class called PartialPermutationSupplier, which implements IntArraySupplier and has two concrete subclasses: the static nested classes Long and BigInteger.
  The int[]representation of a partial permutation should use -1 for the holes.
  Hint: use PermutationSupplier.java as template for this class.
  (This is the most challenging class to be implemented, because you have to come up with efficient algorithms for the methods computeNext() and unrank().)

Your pull request should also contain:

• Spock unit tests - see for example PermutationsSpec.groovy
• examples - should be placed in streamplify-examples
• documentation (using Asciidoctor)

In order to prevent that two people work on the same thing, leave a comment here to claim this issue before starting to work on it.

Happy coding, and don't hesitate to ask for clarification and guidance.

Can Streamplify be used to produce k-permutations of n?

Can Streamplify be used to produce k-permutations of n (https://en.wikipedia.org/wiki/Permutation#k-permutations_of_n)?

For instance:

P(n,r)=P(5,3)=5!(5−3)!= 60 (https://www.calculatorsoup.com/calculators/discretemathematics/permutations.php?n=5&r=3&action=solve)

Or for n = {Alice, Bob, Eve, Mallory} to produce P(4,2)=4!(4−2)!=12 results:
(Alice, Bob)
(Alice, Eve)
(Alice, Mallory)
(Bob, Alice)
(Bob, Eve)
(Bob, Mallory)
(Eve, Alice)
(Eve, Bob)
(Eve, Mallory)
(Mallory, Alice)
(Mallory, Bob)
(Mallory, Eve)

Thank you.

Add support for streams providing the elements of a power set.

This is an up-for-grabs issue, so hurry up and grab it!

Your task is to add support for streams providing the elements of a power set.

Consult the implementation of the other combinatorics classes (permutations, combinations, Cartesian product) and structure your code in a similar way:

• put your classes in a package named org.beryx.streamplify.powerset.
• create a subclass of LongIndexedSpliterator called LongPowerSet, which can be used for power sets with a cardinality that fits in a long (that is, for sets with at most 63 elements).
  Hint: use LongPermutations.java as template for this class.
• create a subclass of BigIntegerIndexedSpliterator called BigIntegerPowerSet, which allows power sets of virtually any cardinality.
  Hint: use BigIntegerPermutations.java as template for this class.
• create a StreamableProxy calledPowerSet, which delegates to either LongPowerSet or BigIntegerPowerSet.
  Hint: use Permutations.java as template for this class.
• create an abstract class called PowerSetSupplier, which implements IntArraySupplier and has two concrete subclasses: the static nested classes Long and BigInteger.
  Hint: use PermutationSupplier.java as template for this class.
  (This is the most challenging class to be implemented, because you have to come up with efficient algorithms for the methods computeNext() and unrank().)

Your pull request should also contain:

• Spock unit tests - see for example PermutationsSpec.groovy
• examples - should be placed in streamplify-examples
• documentation (using Asciidoctor) - in user_guide.adoc, describe how to use your new feature

In order to prevent that two people work on the same thing, leave a comment here to claim this issue before starting to work on it.

Happy coding, and don't hesitate to ask for clarification and guidance.

Add support for derangement streams

This is an up-for-grabs issue, so hurry up and grab it!

Your task is to add support for derangements streams.

A derangement stream can be easily obtained by filtering out the permutations that have items appearing on their original positions:

new Permutations(n)
        .stream()
        .filter(perm -> Arrays.stream(perm).noneMatch(i -> perm[i] == i))

This is, however, a computationally expensive solution. Therefore, your job is to implement efficient classes for derangement streams.

Consult the implementation of the other combinatorics classes (permutations, combinations, Cartesian product) and structure your code in a similar way:

• put your classes in a package named org.beryx.streamplify.derangement.
• create a subclass of LongIndexedSpliterator called LongDerangements, which can be used for derangements with a cardinality that fits in a long (that is, for sets with at most 21 elements).
  Hint: use LongPermutations.java as template for this class.
• create a subclass of BigIntegerIndexedSpliterator called BigIntegerDerangements, which allows derangements of virtually any cardinality.
  Hint: use BigIntegerPermutations.java as template for this class.
• create a StreamableProxy calledDerangements, which delegates to either LongDerangements or BigIntegerDerangements.
  Hint: use Permutations.java as template for this class.
• create an abstract class called DerangementSupplier, which implements IntArraySupplier and has two concrete subclasses: the static nested classes Long and BigInteger.
  Hint: use PermutationSupplier.java as template for this class.
  (This is the most challenging class to be implemented, because you have to come up with efficient algorithms for the methods computeNext() and unrank().)

Your pull request should also contain:

• Spock unit tests - see for example PermutationsSpec.groovy
• examples - should be placed in streamplify-examples
• documentation (using Asciidoctor)

In order to prevent that two people work on the same thing, leave a comment here to claim this issue before starting to work on it.

Happy coding, and don't hesitate to ask for clarification and guidance.