[m-rev.] for review: describe the clusters of related library modules

[Julien Fischer]

On Thu, 8 Jan 2026 at 22:53, Zoltan Somogyi <zoltan.somogyi at runbox.com> wrote:
>
>
> On Thu, 8 Jan 2026 21:06:46 +1100, Julien Fischer <jfischer at opturion.com> wrote:
> > > +- rbtree is the implementation of maps using red-black trees, which are
> > > +  a different kind of balanced tree.
> >
> > It's probably worth mentioning the rbtrees support entries with duplicate keys,
> > as the only times I can recall them actually being used (in mprof and in a
> > bunch of Opturion's applications), that support was the deciding factor.
>
> Are you sure about that?

Yes.

> The insert predicate's entry in the interface is:
>
>    % Inserts a new key-value pair into the tree.
>     % Fails if the key is already in the tree.
>     %
> :- pred insert(K::in, V::in, rbtree(K, V)::in, rbtree(K, V)::out) is semidet.

The rbtree module provides a separate insert_duplicate predicate.

> There is potentially another cluster that I am not knowledgable enough about
> to describe: the random modules. If you want to describe any of these, please
> do so.

The relationship between the random modules is more obvious, because
1. RNGs are all instances of the type classes in the random module.
2. The RNG instances are all submodules of the random module.

In short, the random modules are not quite the same as the clusters being
described here, because there is already more inherent structure present.

> > bags ought to be listed as a variant of sets.
>
> Yes, but they can also be thought of as a variant of maps, with values being integers
> whose only updates are increments and decrements. And adding them to the set
> cluster would require adding a third subcluster that differs in kind from the other two.

My concern was a user looking at all this and wondering if multisets
are provided.

> As the attached interdiff shows, I followed your other suggestions.
>
> I will commit after making the switch from /**/ to %. Any further comments I will
> handle post-commit.

That looks fine.

Julien.