bug#62366: 30.0.50; Doc: add-to-list: destructive?

[Michael Heerdegen]

Hello,

An example to demonstrate what I want to suggest: I use the following
piece of code in my personal customization of Calc:

#+begin_src emacs-lisp
(when (eq calc-language 'latex)
  (add-to-list 'math-expr-opers (list "\\cdot" '* 191 190))))
#+end_src

It is important that this code does not modify the list in
`math-expr-opers' destructively because this list shares a sublist that
is the value of a different variable I must avoid to change by side
effect.

AFAIK `add-to-list' is safe in that regard unless you specify the APPEND
argument (where it suggests itself that the operation is destructive).

So, can we add this simple detail to the docstring of `add-to-list':
that this function doesn't modify the list that the LIST-VAR is bound to
unless APPEND is non-nil?  It would be strange if this would not be the
case, still, I think it would be good to speak this out.

TIA,

Michael.


In GNU Emacs 30.0.50 (build 27, x86_64-pc-linux-gnu, cairo version
 1.16.0) of 2023-03-20 built on drachen
Repository revision: aa54a24570e526b5438264caacf405a2370ba9d3
Repository branch: master
Windowing system distributor 'The X.Org Foundation', version 11.0.12011000
System Description: Debian GNU/Linux 11 (bullseye)