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

[Zoltan Somogyi]

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? 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.
 
> assoc_lists can also be considered an implementation of maps (in addition
> to being lists).

Yes, if you squint, but they are *lousy* as a general implementation of maps,
so I am comfortable leaving them unmentioned in the map cluster.

> As can, bitmap, hash_table and version_hash_table.

I don't know enough about those to be confident in describing them.

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.

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

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.

Zoltan.



-------------- next part --------------
A non-text attachment was scrubbed...
Name: INTERDIFF.cluster
Type: application/octet-stream
Size: 4646 bytes
Desc: not available
URL: <http://lists.mercurylang.org/archives/reviews/attachments/20260108/325a63d2/attachment.obj>