Skip to content

[COLLECTIONS-897] Add LexicographicPermutationIterator - #721

Open
hextriclosan wants to merge 1 commit into
apache:masterfrom
hextriclosan:COLLECTIONS-897-LexicographicPermutationIterator
Open

[COLLECTIONS-897] Add LexicographicPermutationIterator#721
hextriclosan wants to merge 1 commit into
apache:masterfrom
hextriclosan:COLLECTIONS-897-LexicographicPermutationIterator

Conversation

@hextriclosan

@hextriclosan hextriclosan commented Aug 3, 2026

Copy link
Copy Markdown

Add an Iterator<List> that generates the permutations of a collection in lexicographical order, complementing PermutationIterator, which uses the Steinhaus-Johnson-Trotter ordering.

Elements are ordered by their natural ordering, or by a Comparator supplied to the two-argument constructor, which also allows permuting elements that do not implement Comparable. Each call to next() advances by the standard next-permutation step: locate the pivot, swap it with its successor, then reverse the descending tail. Equal elements are not distinguished, so an input with duplicates yields fewer than n! permutations. An empty collection yields exactly one empty list, as 0! = 1. remove() is unsupported.

Comparator dispatch follows the java.util.TreeMap pattern of testing the comparator field for null on each comparison; benchmarking showed no measurable difference against normalizing null to Comparator.naturalOrder() in the constructor.

Tests extend AbstractIteratorTest to cover the Iterator contract, and add cases for lexicographical exhaustivity, duplicate handling, custom and reverse comparators, non-Comparable elements, stream traversal, exhaustion, and equals/hashCode.

Thanks for your contribution to Apache Commons! Your help is appreciated!

Before you push a pull request, review this list:

  • Read the contribution guidelines for this project.
  • Read the ASF Generative Tooling Guidance if you use Artificial Intelligence (AI).
  • I used AI to create any part of, or all of, this pull request. Which AI tool was used to create this pull request, and to what extent did it contribute? Claude for polishing documentation.
  • Run a successful build using the default Maven goal with mvn; that's mvn on the command line by itself.
  • Write unit tests that match behavioral changes, where the tests fail if the changes to the runtime are not applied. This may not always be possible, but it is a best practice.
  • Write a pull request description that is detailed enough to understand what the pull request does, how, and why.
  • Each commit in the pull request should have a meaningful subject line and body. Note that a maintainer may squash commits during the merge process.

Add an Iterator<List<E>> that generates the permutations of a collection in
lexicographical order, complementing PermutationIterator, which uses the
Steinhaus-Johnson-Trotter ordering.

Elements are ordered by their natural ordering, or by a Comparator supplied
to the two-argument constructor, which also allows permuting elements that
do not implement Comparable. Each call to next() advances by the standard
next-permutation step: locate the pivot, swap it with its successor, then
reverse the descending tail. Equal elements are not distinguished, so an
input with duplicates yields fewer than n! permutations. An empty collection
yields exactly one empty list, as 0! = 1. remove() is unsupported.

Comparator dispatch follows the java.util.TreeMap pattern of testing the
comparator field for null on each comparison; benchmarking showed no
measurable difference against normalizing null to Comparator.naturalOrder()
in the constructor.

Tests extend AbstractIteratorTest to cover the Iterator contract, and add
cases for lexicographical exhaustivity, duplicate handling, custom and
reverse comparators, non-Comparable elements, stream traversal, exhaustion,
and equals/hashCode.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant