GNU bug report logs - #59325
The documentation of `map` is confusing

Previous Next

To reply to this bug, email your comments to 59325 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Jacob Hrbek <kreyren <at> rixotstudio.cz>
To: "bug-guile <at> gnu.org" <bug-guile <at> gnu.org>
Subject: The documentation of `map` is confusing
Date: Thu, 17 Nov 2022 00:42:03 +0000

[Message part 1 (text/plain, inline)]

The sentence '-- Scheme Procedure: map' is defined twice each with different inputs and explanation:

-- Scheme Procedure: map proc arg1 arg2 ...
-- Scheme Procedure: map-in-order proc arg1 arg2 ...
-- C Function: scm_map (proc, arg1, args)
Apply PROC to each element of the list ARG1 (if only two arguments
are given), or to the corresponding elements of the argument lists
(if more than two arguments are given). The result(s) of the
procedure applications are saved and returned in a list. For
‘map’, the order of procedure applications is not specified,
‘map-in-order’ applies the procedure from left to right to the list
elements.
...

-- Scheme Procedure: map f lst1 lst2 ...
Map the procedure over the list(s) LST1, LST2, ... and return a
list containing the results of the procedure applications. This
procedure is extended with respect to R5RS, because the argument
lists may have different lengths. The result list will have the
same length as the shortest argument lists. The order in which F
will be applied to the list element(s) is not specified.

Thus proposing:

- Take inspiration from racket[https://docs.racket-lang.org/guide/Lists__Iteration__and_Recursion.html] and add a sensible example code e.g:

(map sqrt '(1 4 9 16))
=> (1 2 3 4)

- Keep only one

-- Jacob "Kreyren" Hrbek

[Message part 2 (text/html, inline)]

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.