GNU bug report logs - #55562
28.1.50; Wrong hash table return values in Elisp manual

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 55562 in the body.
You can then email your comments to 55562 AT debbugs.gnu.org in the normal way.

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

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

From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
To: bug-gnu-emacs <at> gnu.org
Subject: 28.1.50; Wrong hash table return values in Elisp manual
Date: Sat, 21 May 2022 23:29:04 +0300

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

Severity: minor
Tags: patch

0. emacs -Q
1. C-h f clrhash RET

> Clear hash table TABLE and return it.

2. C-h S clrhash RET

> Common Lisp note: In Common Lisp, ‘clrhash’ returns the empty
> TABLE.  In Emacs Lisp, it returns ‘nil’.

It seems the following changes never propagated to the manual:

(Fputhash): Return `value' rather than nil.
d9c4f922fb 2000-07-03 06:59:05 +0000
https://git.sv.gnu.org/cgit/emacs.git/commit/?id=d9c4f922fb

* fns.c (Fputhash): Document return value.
a54e348216 2011-06-06 18:39:26 -0700
https://git.sv.gnu.org/cgit/emacs.git/commit/?id=a54e348216

And the following change wasn't announced in etc/NEWS either:

(Fclrhash): Return TABLE.
ccd8f7fe14 2008-01-25 10:01:15 +0000
https://git.sv.gnu.org/cgit/emacs.git/commit/?id=ccd8f7fe14

Is there any point in announcing the status quo, or can we just update
the manual, e.g. as follows?

[0001-Fix-hash-table-function-return-values-in-manual.patch (text/x-diff, inline)]

From b63ec2658f1c8782620c7418c8282f29249333cd Mon Sep 17 00:00:00 2001
From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
Date: Sat, 21 May 2022 23:11:33 +0300
Subject: [PATCH] Fix hash table function return values in manual

* doc/lispref/hash.texi (Hash Access): Reconcile documented return
values of puthash and clrhash with their respective docstrings.
---
 doc/lispref/hash.texi | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi
index a566d89824..34eda45b23 100644
--- a/doc/lispref/hash.texi
+++ b/doc/lispref/hash.texi
@@ -203,7 +203,8 @@ Hash Access
 @defun puthash key value table
 This function enters an association for @var{key} in @var{table}, with
 value @var{value}.  If @var{key} already has an association in
-@var{table}, @var{value} replaces the old associated value.
+@var{table}, @var{value} replaces the old associated value.  This
+function always returns @var{value}.
 @end defun
 
 @defun remhash key table
@@ -219,10 +220,7 @@ Hash Access
 @defun clrhash table
 This function removes all the associations from hash table @var{table},
 so that it becomes empty.  This is also called @dfn{clearing} the hash
-table.
-
-@b{Common Lisp note:} In Common Lisp, @code{clrhash} returns the empty
-@var{table}.  In Emacs Lisp, it returns @code{nil}.
+table.  @code{clrhash} returns the empty @var{table}.
 @end defun
 
 @defun maphash function table
-- 
2.35.1

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

Thanks,

-- 
Basil

In GNU Emacs 28.1.50 (build 1, x86_64-pc-linux-gnu)
 of 2022-05-21 built on tia
Repository revision: 139bfa1a0884dbd2600fc1bd11d11f41d3f9ef94
Repository branch: wt/emacs-28-nox
System Description: Debian GNU/Linux bookworm/sid

Configured using:
 'configure CC=gcc-12 'CFLAGS=-O2 -march=native'
 --prefix=/home/blc/.local --program-suffix=-28-nox
 --with-file-notification=yes --with-x-toolkit=no --without-x'

Configured features:
ACL DBUS GMP GNUTLS GPM JSON LCMS2 LIBSELINUX LIBSYSTEMD LIBXML2 MODULES
NOTIFY INOTIFY PDUMPER SECCOMP SOUND THREADS XIM ZLIB

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: "Basil L. Contovounesios" <contovob <at> tcd.ie>,
 Stefan Monnier <monnier <at> iro.umontreal.ca>,
 Daniel Colascione <dancol <at> dancol.org>
Cc: 55562 <at> debbugs.gnu.org
Subject: Re: bug#55562: 28.1.50; Wrong hash table return values in Elisp manual
Date: Sun, 22 May 2022 08:10:33 +0300

[Adding Stefan and Daniel to the CC.]

> Date: Sat, 21 May 2022 23:29:04 +0300
> From:  "Basil L. Contovounesios" via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
> 
> Severity: minor
> Tags: patch
> 
> 0. emacs -Q
> 1. C-h f clrhash RET
> 
> > Clear hash table TABLE and return it.
> 
> 2. C-h S clrhash RET
> 
> > Common Lisp note: In Common Lisp, ‘clrhash’ returns the empty
> > TABLE.  In Emacs Lisp, it returns ‘nil’.
> 
> It seems the following changes never propagated to the manual:
> 
> (Fputhash): Return `value' rather than nil.
> d9c4f922fb 2000-07-03 06:59:05 +0000
> https://git.sv.gnu.org/cgit/emacs.git/commit/?id=d9c4f922fb
> 
> * fns.c (Fputhash): Document return value.
> a54e348216 2011-06-06 18:39:26 -0700
> https://git.sv.gnu.org/cgit/emacs.git/commit/?id=a54e348216
> 
> And the following change wasn't announced in etc/NEWS either:
> 
> (Fclrhash): Return TABLE.
> ccd8f7fe14 2008-01-25 10:01:15 +0000
> https://git.sv.gnu.org/cgit/emacs.git/commit/?id=ccd8f7fe14
> 
> Is there any point in announcing the status quo, or can we just update
> the manual, e.g. as follows?
> 
> 
> >From b63ec2658f1c8782620c7418c8282f29249333cd Mon Sep 17 00:00:00 2001
> From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
> Date: Sat, 21 May 2022 23:11:33 +0300
> Subject: [PATCH] Fix hash table function return values in manual
> 
> * doc/lispref/hash.texi (Hash Access): Reconcile documented return
> values of puthash and clrhash with their respective docstrings.
> ---
>  doc/lispref/hash.texi | 8 +++-----
>  1 file changed, 3 insertions(+), 5 deletions(-)
> 
> diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi
> index a566d89824..34eda45b23 100644
> --- a/doc/lispref/hash.texi
> +++ b/doc/lispref/hash.texi
> @@ -203,7 +203,8 @@ Hash Access
>  @defun puthash key value table
>  This function enters an association for @var{key} in @var{table}, with
>  value @var{value}.  If @var{key} already has an association in
> -@var{table}, @var{value} replaces the old associated value.
> +@var{table}, @var{value} replaces the old associated value.  This
> +function always returns @var{value}.
>  @end defun
>  
>  @defun remhash key table
> @@ -219,10 +220,7 @@ Hash Access
>  @defun clrhash table
>  This function removes all the associations from hash table @var{table},
>  so that it becomes empty.  This is also called @dfn{clearing} the hash
> -table.
> -
> -@b{Common Lisp note:} In Common Lisp, @code{clrhash} returns the empty
> -@var{table}.  In Emacs Lisp, it returns @code{nil}.
> +table.  @code{clrhash} returns the empty @var{table}.
>  @end defun
>  
>  @defun maphash function table
> -- 
> 2.35.1
> 
> Thanks,
> 
> -- 
> Basil
> 
> In GNU Emacs 28.1.50 (build 1, x86_64-pc-linux-gnu)
>  of 2022-05-21 built on tia
> Repository revision: 139bfa1a0884dbd2600fc1bd11d11f41d3f9ef94
> Repository branch: wt/emacs-28-nox
> System Description: Debian GNU/Linux bookworm/sid
> 
> Configured using:
>  'configure CC=gcc-12 'CFLAGS=-O2 -march=native'
>  --prefix=/home/blc/.local --program-suffix=-28-nox
>  --with-file-notification=yes --with-x-toolkit=no --without-x'
> 
> Configured features:
> ACL DBUS GMP GNUTLS GPM JSON LCMS2 LIBSELINUX LIBSYSTEMD LIBXML2 MODULES
> NOTIFY INOTIFY PDUMPER SECCOMP SOUND THREADS XIM ZLIB

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

From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 55562 <at> debbugs.gnu.org, Daniel Colascione <dancol <at> dancol.org>,
 Stefan Monnier <monnier <at> iro.umontreal.ca>
Subject: Re: bug#55562: 28.1.50; Wrong hash table return values in Elisp manual
Date: Mon, 27 Jun 2022 23:43:59 +0300

Eli Zaretskii [2022-05-22 01:10 -0400] wrote:

> [Adding Stefan and Daniel to the CC.]
>
>> Date: Sat, 21 May 2022 23:29:04 +0300
>> From:  "Basil L. Contovounesios" via "Bug reports for GNU Emacs,
>>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
>> 
>> Severity: minor
>> Tags: patch
>> 
>> 0. emacs -Q
>> 1. C-h f clrhash RET
>> 
>> > Clear hash table TABLE and return it.
>> 
>> 2. C-h S clrhash RET
>> 
>> > Common Lisp note: In Common Lisp, ‘clrhash’ returns the empty
>> > TABLE.  In Emacs Lisp, it returns ‘nil’.
>> 
>> It seems the following changes never propagated to the manual:
>> 
>> (Fputhash): Return `value' rather than nil.
>> d9c4f922fb 2000-07-03 06:59:05 +0000
>> https://git.sv.gnu.org/cgit/emacs.git/commit/?id=d9c4f922fb
>> 
>> * fns.c (Fputhash): Document return value.
>> a54e348216 2011-06-06 18:39:26 -0700
>> https://git.sv.gnu.org/cgit/emacs.git/commit/?id=a54e348216
>> 
>> And the following change wasn't announced in etc/NEWS either:
>> 
>> (Fclrhash): Return TABLE.
>> ccd8f7fe14 2008-01-25 10:01:15 +0000
>> https://git.sv.gnu.org/cgit/emacs.git/commit/?id=ccd8f7fe14
>> 
>> Is there any point in announcing the status quo, or can we just update
>> the manual, e.g. as follows?
>> 
>> >From b63ec2658f1c8782620c7418c8282f29249333cd Mon Sep 17 00:00:00 2001
>> From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
>> Date: Sat, 21 May 2022 23:11:33 +0300
>> Subject: [PATCH] Fix hash table function return values in manual
>> 
>> * doc/lispref/hash.texi (Hash Access): Reconcile documented return
>> values of puthash and clrhash with their respective docstrings.
>> ---
>>  doc/lispref/hash.texi | 8 +++-----
>>  1 file changed, 3 insertions(+), 5 deletions(-)
>> 
>> diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi
>> index a566d89824..34eda45b23 100644
>> --- a/doc/lispref/hash.texi
>> +++ b/doc/lispref/hash.texi
>> @@ -203,7 +203,8 @@ Hash Access
>>  @defun puthash key value table
>>  This function enters an association for @var{key} in @var{table}, with
>>  value @var{value}.  If @var{key} already has an association in
>> -@var{table}, @var{value} replaces the old associated value.
>> +@var{table}, @var{value} replaces the old associated value.  This
>> +function always returns @var{value}.
>>  @end defun
>>  
>>  @defun remhash key table
>> @@ -219,10 +220,7 @@ Hash Access
>>  @defun clrhash table
>>  This function removes all the associations from hash table @var{table},
>>  so that it becomes empty.  This is also called @dfn{clearing} the hash
>> -table.
>> -
>> -@b{Common Lisp note:} In Common Lisp, @code{clrhash} returns the empty
>> -@var{table}.  In Emacs Lisp, it returns @code{nil}.
>> +table.  @code{clrhash} returns the empty @var{table}.
>>  @end defun
>>  
>>  @defun maphash function table
>> -- 
>> 2.35.1

Is this suitable for Emacs 28?

Thanks,

-- 
Basil

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: "Basil L. Contovounesios" <contovob <at> tcd.ie>
Cc: 55562 <at> debbugs.gnu.org, dancol <at> dancol.org, monnier <at> iro.umontreal.ca
Subject: Re: bug#55562: 28.1.50; Wrong hash table return values in Elisp manual
Date: Tue, 28 Jun 2022 05:35:57 +0300

> From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
> Cc: Stefan Monnier <monnier <at> iro.umontreal.ca>,  Daniel Colascione
>  <dancol <at> dancol.org>,  55562 <at> debbugs.gnu.org
> Date: Mon, 27 Jun 2022 23:43:59 +0300
> 
> Is this suitable for Emacs 28?

If the behavior is the same there, yes.

Message #21 received at 55562-done <at> debbugs.gnu.org (full text, mbox):

From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 55562-done <at> debbugs.gnu.org, dancol <at> dancol.org, monnier <at> iro.umontreal.ca
Subject: Re: bug#55562: 28.1.50; Wrong hash table return values in Elisp manual
Date: Tue, 28 Jun 2022 10:06:46 +0300

found 55562 24.1
close 55562 28.2
quit

Eli Zaretskii [2022-06-27 22:35 -0400] wrote:

>> From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
>> Cc: Stefan Monnier <monnier <at> iro.umontreal.ca>,  Daniel Colascione
>>  <dancol <at> dancol.org>,  55562 <at> debbugs.gnu.org
>> Date: Mon, 27 Jun 2022 23:43:59 +0300
>> 
>> Is this suitable for Emacs 28?
>
> If the behavior is the same there, yes.

The puthash behaviour has been with us since Emacs 22, and the clrhash
behaviour since Emacs 24, it's just the Elisp manual that was never
updated accordingly.

So I've now updated the manual in emacs-28, and I'm closing this report.

Fix hash table function return values in manual
091b22cb12 2022-06-28 10:03:53 +0300
https://git.sv.gnu.org/cgit/emacs.git/commit/?id=091b22cb12

Thanks,

-- 
Basil

Previous Next

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