Subject: Re: bug#72347: Mismatch between documentation and real implementation of list-index

From: Tomas Volf <[email-masked]>
Date: Mon, 29 Jul 2024 12:28:00 +0200

Hello,

On 2024-07-29 00:34:14 +0000, Marius via Bug reports for GUILE, GNU's Ubiquitous Extension Language wrote:
> Good evening,
>
> I don't know if this is actually a Guile bug or a documentation bug, but I'm currently learning Guile from the "Guile reference manual" and I've found a mismatch between what the documentation says and what "my" guile does. I use Guile 3.0.9.
>
> In my Guile instance (from what I can deduce), last-index is a procedure that returns the index of the first element of a list that matches with a s-expresion.
>
> For example:
>
> (list-index '(1 2 3) 3) -> 2
> (list-index '(height width) 'width) -> 1
>
> But the documentation says otherwise (<https://www.gnu.org/software/guile//manual/guile.html#SRFI_002d1-Filtering-and-Partitioning>):
>
> list-index pred lst1 lst2 ...
>
> Returns the index of the first set of elements, one from each of lst1 lst2 ..., which satisfies pred.

This is documentation for SRFI-1, and that is not available by default (at least
not fully), you need to (use-modules) it.  See below.

>
>
> If I try to run list-index examples (from the documentation) I get an error because it doesn't know how to deal with a procedure as the first argument.
>
>
> I'm missing something? I understand that list-index it's defined in SRFI-1 and maybe a Guile definition is shadowing the SRFI-1 definition. But where is the Guile documentation for this shadowing list-index? In the Guile Reference Manual list-index it's only described inside SRFI-1 module.

It seems that Guile provides 2 different list-index procedures.  One defined in
the ice-9/boot-9.scm, and one in the srfi-1 module.  By default the boot-9's one
is available.

    $ guile -q
    GNU Guile 3.0.9
    Copyright (C) 1995-2023 Free Software Foundation, Inc.

    Guile comes with ABSOLUTELY NO WARRANTY; for details type `,show w'.
    This program is free software, and you are welcome to redistribute it
    under certain conditions; type `,show c' for details.

    Enter `,help' for help.
    scheme@(guile-user)> list-index
    $1 = #<procedure list-index (l k)>
    scheme@(guile-user)> ,use (srfi srfi-1)
    scheme@(guile-user)> list-index
    $2 = #<procedure list-index (pred clist1 . rest)>

Notice that by importing srfi-1 the list-index changes to the documented one.

You are right that the "default" list-index indeed does not seem to be
documented.  It also uses `eq?' for comparisons and does not allow changing
that.

I hope this sheds some light on the problem.

Tomas

--
There are only two hard things in Computer Science:
cache invalidation, naming things and off-by-one errors.