bug#34708: alist-get has unclear documentation

[Michael Heerdegen <michael_heerdegen@web.de>]

Drew Adams <drew.adams@oracle.com> writes:

> Alists can be handled in more than one way when
> setting and deleting keys.  The doc needs to tell
> us what `setf' with `alist-get' does to realize
> these things.

I agree.

I'm in the middle of preparing a patch.  While doing that, two questions
arose:

(1) "When using it to set a value, optional argument REMOVE non-nil
means to remove KEY from ALIST if the new value is `eql' to DEFAULT."

I wonder if there are use cases where the user wants something different
than `eql'?  E.g. `equal' when the associations are strings?  Note that
this is something different than TESTFN which is for comparing keys.

(2) The remove feature has a strange corner case.  Normally the first
found association is removed, but if you somehow manage to add the same
cons (in the sense of `eq') to the same alist, all of them are removed.
Compare e.g.

(progn
  (setq my-alist '((a . 1) (a . 1) (b . 2)))
  (setf (alist-get 'a my-alist nil 'remove) nil))

;; my-alist ==> ((a . 1) (b . 2))

  vs.

(progn
  (setq my-alist '((a . 1) (b . 2)))
  (push (car my-alist) my-alist) ;; my-alist ==> (#1=(a . 1) #1# (b . 2))
  (setf (alist-get 'a my-alist nil 'remove) nil))
;; my-alist ==> ((b . 2))

This is because the code uses delq to delete a found cons, and delq
removes all `eq' elements.

Is it worth to document or change that?


Michael.