[m-rev.] for review: re-order the interface of the ranges module

[Zoltan Somogyi]

On 2024-03-31 01:54 +11:00 AEDT, "Julien Fischer" <jfischer at opturion.com> wrote:
> Re-order the interface of the ranges module.

The reorder is fine, though ...

> Make the interface of the ranges module consistent with that of the other set
> modules.

... ranges.m is not there yet. I added NOTE_TO_IMPLEMENTORS comments
about some of the missing things. I also clarified (I hope) several of the
comments on exported operations.

I had a look at the code of the module, and improved var names in
the initial few functions/predicates, but then realized that we need not one
naming scheme, but two, due to the asymmetrical design of the ranges
data structure. Users see a range as Lo .. Hi, with Lo and Hi both included;
the internal representation is Lo .. Hi, with only Hi included.

One way we can handle is by using two different naming conventions,
such as Min/Max when dealing with both-included ranges, and Lo/Hi when
dealing with only-high-side included ranges, though a scheme that
puts the asymmetry of the bounds in front of readers eyes would be better.

However, another way, which I would prefer if it is viable, is to simply change
the meaning of the data structure to include the lower bound in the set as well.
This would however require a rewrite of all existing predicates. Any such rewrite
would need a comprehensive test suite. I don't think hard_coded/test_ranges.m
is comprehensive enough.

Julien, you added ranges.m to Mercury by copying it from G12.
Did its initial design consider using this approach? If not, do you know
why not? Was it maybe based on existing code in another language?
And has anyone looked into making this representation change
since then?

Another, separate issue is that this module needs a top-of-module comment
explaining the situations that call for its use. We should also have a big
comment in set.m that

- lists the many, many other modules that also implement sets,
- specifies the situations that call for the use of each of them.

This way, each of those modules can point back at this comment
instead of listing all the alternatives itself.

Zoltan.