[m-rev.] Bug in API documentation

[Volker Wysk]

Am Mittwoch, dem 12.11.2025 um 16:33 +1100 schrieb 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.

get_values_for_key sounds good to me.

Volker