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

[Julien Fischer]

On Sun, 31 Mar 2024, Zoltan Somogyi wrote:

>
> 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.

Thanks, I will address those when I get around addressing the ones I
added.

> 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.

The existing contents of that test are just some specific regression
tests I shifted across from the Opturion version; I have been working on
extending it to provide better coverage of the entire module. We should
hold off making any signficant changes until those new tests are in place.

> 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?

Mark Brown is the original author; if his memory stretches back to 2006,
he might be able to tell us.

> Was it maybe based on existing code in another language?

AFAIK, it has always been written in Mercury.

> And has anyone looked into making this representation change
> since then?

No.

> Another, separate issue is that this module needs a top-of-module comment
> explaining the situations that call for its use.

That's already on my list of things to do ;-)

> 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.

Agreed.

Julien.