[m-rev.] Bug in API documentation

[Peter Wang]

On Wed, 12 Nov 2025 13:48:48 +1100 Julien Fischer <jfischer at opturion.com> wrote:
> 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.

I'm not convinced. Just write the if-then-else at the call site(s),
or add a utility predicate to your application.

Peter