[m-rev.] for review: improve description of ranges module

[Zoltan Somogyi]

On Fri, 17 Jan 2025 15:42:55 +1100, Julien Fischer <jfischer at opturion.com> wrote:
> Improve description of the ranges module.

The diff improves the module, so you can go ahead and commit it.

I do have a question though. Given the term ranges(N, M, ...),
what led to the decision to make this represent the values
between N+1 and M both inclusive, and not the values between
N and M both inclusive?

The latter would avoid the limitation about not being able to store min_int.
One would still have to be careful about not trying to subtract one
from the N of the first range in a set, but then again, the current code
must already handle the mirror image of this, i.e. not adding one to the M
of the last range in a set.

I also note that while such half-open interval representations are common
in e.g. C programs, they are also a fruitful source of bugs, because in effect
they almost double the programmer's workload: instead of figuring out
how to handle how to handle one closed interval-end and then just mirroring
the code for the other closed interval-end, they must figure out how to handle
an open interval-end, which is subtly different. This same effect also doubles
the work required to construct a correctness argument (though most programmers
don't bother :-()

My overall recommendation would be: if at all possible, we should switch
to using fully closed intervals, though only after constructing a comprehensive
set of tests for all the currently supported operations on ranges. The correctness
of both the existing ranges implementation, and of any replacement, could
be checked automatically by

- defining operations to convert values of the ranges type to set(int),
- doing the operation on the set(int) representation, and
- converting back to ranges.

Overall, I prefer fixing footguns to documenting them. When I was
still teaching, I used to tell my students a quote I found somewhere
about this: "You cannot make a pussycat out of a lion
by describing its claws in a reference manual."

Zoltan.