[m-rev.] Bug in API documentation

[Julien Fischer]

On Wed, 12 Nov 2025 at 16:30, Volker Wysk <post at volker-wysk.de> wrote:
>
> Am Mittwoch, dem 12.11.2025 um 13:48 +1100 schrieb Julien Fischer:
> > On Wed, 12 Nov 2025 at 02:28, Volker Wysk <post at volker-wysk.de> wrote:
> > >
> > > Am Mittwoch, dem 12.11.2025 um 01:37 +1100 schrieb Zoltan Somogyi:
> > > >
> > > > 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.
> > >
> > > Your guess is right.
> > >
> > > In my case, having no occurrences of values for a given key is perfectly
> > > okay. It doesn't mean failure. It should result in an empty list.
> > >
> > > I have a mapping from file names (last path component of each path) to
> > > the
> > > full paths. There can be none, one or multiple such paths for such a
> > > file
> > > name. When there are none, the result should be an 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.
> > >
> > > If you want a crystal-clear name, it will be a long one. But what about
> > > "occurrences" or maybe "occurs"?
> >
> > My suggestion would be get_values_for_key.
>
> Or just get_values.

get_values is too similar to values (e.g in the map modules), which returns
all of the values stored in the map.

Julien.