hextriclosan commented on PR #721:
URL:
https://github.com/apache/commons-collections/pull/721#issuecomment-5269749462
Fair point, the C++ reference doesn't belong here. Let me restate it in
terms of this library.
Within Java Collections, `Collections.binarySearch` is the pattern: "The
list must be sorted into ascending order according to the natural ordering of
its elements... If it is not sorted, the results are undefined." The JDK
documents the precondition and trusts the caller rather than sorting
defensively.
Within Commons Collections, `CollatingIterator` in this same package does
the same thing. It provides an ordered iteration over a collection of ordered
iterators, states that in the first line of its javadoc, and never sorts its
inputs. Unordered input gives unordered output. That's the precedent I should
have cited from the start.
The substantive reason is about what each design permits. A caller who wants
the complete set can sort before constructing, one line at the call site. A
caller who wants to resume from a previously reached arrangement, or to split
the permutation space across workers by giving each a different starting point,
has no recourse if the constructor sorts. Sorting is not recoverable from
outside the class, so the version that preserves the given order is strictly
the more capable of the two.
What I've pushed documents the precondition, since the javadoc previously
contradicted it, and adds tests pinning it for both natural ordering and a
supplied comparator.
If you'd still rather the complete set be the default, I'd suggest a static
factory such as `overAll(collection)` that sorts a copy, keeping the
start-anywhere behavior available on the constructor.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
