Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Describe the termination behaviour in seq.mli #13767

Merged
merged 1 commit into from
Feb 1, 2025

Conversation

hirrolot
Copy link
Contributor

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 many Seq functions, such as for_all/exists or find/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):

  1. Guaranteed to terminate only if [xs] is finite.
  2. May not terminate if [xs] is infinite.

When expanded, these phrases mean:

  1. Guaranteed to terminate if [xs] is finite, but may or may not terminate if [xs] is infinite.
  2. 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.

stdlib/seq.mli Outdated Show resolved Hide resolved
stdlib/seq.mli Outdated Show resolved Hide resolved
stdlib/seq.mli Outdated Show resolved Hide resolved
stdlib/seq.mli Outdated Show resolved Hide resolved
stdlib/seq.mli Outdated Show resolved Hide resolved
@hirrolot hirrolot requested a review from gasche February 1, 2025 20:22
Copy link
Member

@gasche gasche left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This now looks good to me.

@gasche gasche merged commit a8e304a into ocaml:trunk Feb 1, 2025
38 of 40 checks passed
@gasche
Copy link
Member

gasche commented Feb 1, 2025

Thanks! Merged.

@hirrolot hirrolot deleted the improve-seq-docs branch February 1, 2025 22:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants