[m-rev.] Bug in API documentation

[Zoltan Somogyi]

On Tue, 11 Nov 2025 19:37:31 +1100, Julien Fischer <jfischer at opturion.com> wrote:
> > I'm missing in multi_map (and one_or_more_map) a method of getting all the
> > values corresponding to a key, which returns an empty list, when there are
> > none, instead of failing or throwing an exception.
> 
> For multi_maps, lookup returns an empty list if there are no values
> corresponding
> to a key.  (It throws an exception if the key is *not* present in the
> multi_map, which
> is a different thing.)

Actually, if multi_map.search or multi_map.lookup ever returns an empty list,
then that means that there is a bug in the multi_map module, because it *should*
enforce the invariant that no key is mapped to the empty list of values.

> For one_or_more_maps, by design if a key is present in the one_or_more_map,
> then there must be at least one value associated with it (i.e. you can never
> have a one_or_more_map where there no values associated with a key that
> is present in the map.)

I added one_or_more_map to the standard library as a near-copy of multi_map
not to *add* this invariant (with respect to multi_map), but to *enforce* this
invariant. With multi_map.search, callers must handle the situation of a key
having no matching values in two distinct ways, being prepared for the call failing,
and for the call succeeding with an empty list, even though the latter should never
happen. With one_or_more_map.search, they don't need to prepare for the latter.

I am *guessing* that what Volker wants is to replace code like this:

  ( if multi_map.search(Map, Key, ValuesPrime) then
    Values = ValuesPrime
  else
    Values = []
  )

with a single call. It would be to a predicate that is still a search, not a lookup,
but expresses the failure of the search not by failing, but by returning the empty list.
This could work even in one_or_more_map: the output argument of this predicate would
of course have to have type list(T), not one_or_more(T).

We could provide such a predicate in both modules. The tricky part is naming it.
That is because your program would be more readable with the five lines of code above
than with a single line of code containing a call to a predicate with a non-crystal-clear name.

Zoltan.