[m-rev.] Bug in API documentation

[Julien Fischer]

On Tue, 11 Nov 2025 at 17:24, Volker Wysk <post at volker-wysk.de> wrote:

> Am Dienstag, dem 11.11.2025 um 09:38 +1100 schrieb Julien Fischer:
> > Hi Volker,
> >
> > On Mon, 10 Nov 2025 at 18:07, Volker Wysk <post at volker-wysk.de> wrote:
> >
> > > In the documentation of the multi_map module is this:
> > >
> > >     % If the multi_map has an entry for the given key,
> > >     % succeed once for each of the corresponding values.
> > >     % Otherwise, throw an exception.
> > >     %
> > > :- func lookup(multi_map(K, V), K) = list(V).
> > > :- pred lookup(multi_map(K, V)::in, K::in, list(V)::out) is det.
> > >
> > > The comment doesn't match the declaration.
> >
> > Thanks for reporting that. It's a copy-and-paste error. That's the
> > documentation
> > for nondet_lookup/3 directly below.  (The same thing occurs in the
> > one_or_more_map
> > as well.)
>
> 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.)

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

Julien.