Describe the termination behaviour in seq.mli
#13767
Merged
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
As suggested by @dbuenzli in this comment,
seq.mli
is "littered" with statements like "The sequence [xs] must be finite.
". However, most of these preconditions are too strict, in the sense that manySeq
functions, such asfor_all
/exists
orfind
/find_index
/find_map
/etc., may terminate even on infinite sequences.This PR touches only the documentation of the
Seq
functions.Initially, I planned to make this change after my PR #13750 is merged, but since it got delayed due to a second approval, I assume it's better to improve the documentation now than later.
On phrasing
Two sentences were suggested (mind the order):
Guaranteed to terminate only if [xs] is finite.
May not terminate if [xs] is infinite.
When expanded, these phrases mean:
Guaranteed to terminate if [xs] is finite, but may or may not terminate if [xs] is infinite.
May or may not terminate if [xs] is infinite, and the same for when [xs] is finite.
Clearly, the first one is formally more correct. But since it seems pretty clear that sequence-consuming functions always terminate on finite
xs
/ys
, I decided to use the more concise phrasing.