From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: Paul Eggert Newsgroups: gmane.emacs.bugs Subject: bug#40671: [DOC] modify literal objects Date: Sun, 10 May 2020 10:29:21 -0700 Organization: UCLA Computer Science Department Message-ID: <41d69e2e-561f-743a-e1f0-282b2e22b66c@cs.ucla.edu> References: <012e8bc3-df4b-3884-4e54-5fe7ef4248cb@cs.ucla.edu> <37a54ac2-da80-ca35-9c01-38c8e12a4b5f@yandex.ru> <9375aaeb-2a9a-b307-c793-0d99328201ea@yandex.ru> <7fe0574a-62ae-94fb-2e55-1a69de6ce828@cs.ucla.edu> <91857438-f44a-90f4-dfe2-a32224ba3994@yandex.ru> <880dc34b-46a9-0149-3c6e-0a951a70125d@cs.ucla.edu> <9c46b93e-a855-0be0-7ab0-50cb8c5cd74d@yandex.ru> <48e90f87-1519-9101-d54b-4bfd81a0c936@yandex.ru> <252d6368-ddea-2f41-b53f-cd927ebc3d1d@cs.ucla.edu> <43d93102-d361-f64b-971b-909418b89fca@yandex.ru> <2ca64f28-1255-4135-6e45-0f0e12b9e72d@cs.ucla.edu> <0c7570cb-bf52-a617-bf54-27a47c54e04a@cs.ucla.edu> <04298f7d-f2c0-5186-57d3-522e3d886166@cs.ucla.edu> <88af48c6-bc39-6ab0-59ec-7d537f2d375d@yandex.ru> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="------------312F946E318346DC6D4AB88F" Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="120207"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.7.0 Cc: ke.vigouroux@laposte.net, 40671@debbugs.gnu.org, Michael Heerdegen , Mattias =?UTF-8?Q?Engdeg=C3=A5rd?= , Richard Stallman To: Dmitry Gutov Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sun May 10 19:30:15 2020 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jXpmH-000VAD-Tz for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 10 May 2020 19:30:14 +0200 Original-Received: from localhost ([::1]:39830 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jXpmG-0005pE-EL for geb-bug-gnu-emacs@m.gmane-mx.org; Sun, 10 May 2020 13:30:12 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:38902) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jXpm7-0005oJ-24 for bug-gnu-emacs@gnu.org; Sun, 10 May 2020 13:30:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:38837) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jXpm6-0002hr-N9 for bug-gnu-emacs@gnu.org; Sun, 10 May 2020 13:30:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1jXpm6-0000oY-I0 for bug-gnu-emacs@gnu.org; Sun, 10 May 2020 13:30:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Paul Eggert Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 10 May 2020 17:30:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 40671 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 40671-submit@debbugs.gnu.org id=B40671.15891317753053 (code B ref 40671); Sun, 10 May 2020 17:30:02 +0000 Original-Received: (at 40671) by debbugs.gnu.org; 10 May 2020 17:29:35 +0000 Original-Received: from localhost ([127.0.0.1]:50380 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jXple-0000nA-51 for submit@debbugs.gnu.org; Sun, 10 May 2020 13:29:35 -0400 Original-Received: from zimbra.cs.ucla.edu ([131.179.128.68]:38446) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jXplb-0000mq-9y for 40671@debbugs.gnu.org; Sun, 10 May 2020 13:29:32 -0400 Original-Received: from localhost (localhost [127.0.0.1]) by zimbra.cs.ucla.edu (Postfix) with ESMTP id 01AC41600C3; Sun, 10 May 2020 10:29:25 -0700 (PDT) Original-Received: from zimbra.cs.ucla.edu ([127.0.0.1]) by localhost (zimbra.cs.ucla.edu [127.0.0.1]) (amavisd-new, port 10032) with ESMTP id 33dXNJLjDn6g; Sun, 10 May 2020 10:29:22 -0700 (PDT) Original-Received: from localhost (localhost [127.0.0.1]) by zimbra.cs.ucla.edu (Postfix) with ESMTP id 9AFBA1600C7; Sun, 10 May 2020 10:29:22 -0700 (PDT) X-Virus-Scanned: amavisd-new at zimbra.cs.ucla.edu Original-Received: from zimbra.cs.ucla.edu ([127.0.0.1]) by localhost (zimbra.cs.ucla.edu [127.0.0.1]) (amavisd-new, port 10026) with ESMTP id a5pkyOs67hrG; Sun, 10 May 2020 10:29:22 -0700 (PDT) Original-Received: from [192.168.1.9] (cpe-23-242-74-103.socal.res.rr.com [23.242.74.103]) by zimbra.cs.ucla.edu (Postfix) with ESMTPSA id 493811600C3; Sun, 10 May 2020 10:29:22 -0700 (PDT) Autocrypt: addr=eggert@cs.ucla.edu; prefer-encrypt=mutual; keydata= LS0tLS1CRUdJTiBQR1AgUFVCTElDIEtFWSBCTE9DSy0tLS0tCgptUUlOQkV5QWNtUUJFQURB QXlIMnhvVHU3cHBHNUQzYThGTVpFb243NGRDdmM0K3ExWEEySjJ0QnkycHdhVHFmCmhweHhk R0E5Smo1MFVKM1BENGJTVUVnTjh0TFowc2FuNDdsNVhUQUZMaTI0NTZjaVNsNW04c0thSGxH ZHQ5WG0KQUF0bVhxZVpWSVlYL1VGUzk2ZkR6ZjR4aEVtbS95N0xiWUVQUWRVZHh1NDd4QTVL aFRZcDVibHRGM1dZRHoxWQpnZDdneDA3QXV3cDdpdzdlTnZub0RUQWxLQWw4S1lEWnpiRE5D UUdFYnBZM2VmWkl2UGRlSStGV1FONFcra2doCnkrUDZhdTZQcklJaFlyYWV1YTdYRGRiMkxT MWVuM1NzbUUzUWpxZlJxSS9BMnVlOEpNd3N2WGUvV0szOEV6czYKeDc0aVRhcUkzQUZINmls QWhEcXBNbmQvbXNTRVNORnQ3NkRpTzFaS1FNcjlhbVZQa25qZlBtSklTcWRoZ0IxRApsRWR3 MzRzUk9mNlY4bVp3MHhmcVQ2UEtFNDZMY0ZlZnpzMGtiZzRHT1JmOHZqRzJTZjF0azVlVThN Qml5Ti9iClowM2JLTmpOWU1wT0REUVF3dVA4NGtZTGtYMndCeHhNQWhCeHdiRFZadWR6eERa SjFDMlZYdWpDT0pWeHEya2wKakJNOUVUWXVVR3FkNzVBVzJMWHJMdzYrTXVJc0hGQVlBZ1Jy NytLY3dEZ0JBZndoU In-Reply-To: <88af48c6-bc39-6ab0-59ec-7d537f2d375d@yandex.ru> Content-Language: en-US X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:180024 Archived-At: This is a multi-part message in MIME format. --------------312F946E318346DC6D4AB88F Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 7bit On 5/9/20 8:13 PM, Dmitry Gutov wrote: > You start talking about objects that "should [not] change". And give an example > of an object that _cannot_ change. That's easily altered to also give an example of an object that should not change; see attached patch. > I could understand it if it was describing an existing type system of the > language, or implementation internals, but this is a purely imaginary type > system. objects.texi already talks about the Emacs Lisp type system and specifically mentions strings, conses, etc. as types. Even if one considers the Emacs Lisp type system to be "imaginary", it's reasonable to use the documentation's already-existing terminology here. > the list object didn't change, just an outside reference to its head was > created, The attached patch alters the example so that the list object does change (or at least tries to). > The opposite of "mutable" is "immutable". Are string literals immutable? They are > not. They might be mutable, and they might not be. The documentation deliberately doesn't say, because we don't want to document the details (they have changed in the past and are likely to change in the future). > Overall the phrase "that might be shared" is a good replacement. Why not keep to > it? Because it's not an accurate statement of the problem. The set of objects that might be shared differs from the set of objects that should not change. The Mutability node focuses on the latter set of objects, and gives the former as an example but it is not the only sort of object that should not change. > your new meaning of "mutable" doesn't seem indispensable. That bar is too high, as hardly anything in the manual is *indispensable*. Ihe notion of mutability is good to have in the manual, as it reduces confusion and helps in documentation elsewhere. That's good enough. I'm attaching two patches. The first are the changes mentioned above, and the second is a single patch that combines the first patch with the changes I previously proposed. --------------312F946E318346DC6D4AB88F Content-Type: text/x-patch; charset=UTF-8; name="0001-Update-mutability-doc.patch" Content-Disposition: attachment; filename="0001-Update-mutability-doc.patch" Content-Transfer-Encoding: quoted-printable >From f2f7cff7c72ca399ca49a50ceac660c3b0991d92 Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Sun, 10 May 2020 10:01:46 -0700 Subject: [PATCH] Update mutability doc MIME-Version: 1.0 Content-Type: text/plain; charset=3DUTF-8 Content-Transfer-Encoding: 8bit * doc/lispref/objects.texi (Mutability): Revise in response to Dmitry Gutov=E2=80=99s comments (Bug#40671#420). --- doc/lispref/objects.texi | 33 ++++++++++++++++++++++----------- 1 file changed, 22 insertions(+), 11 deletions(-) diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index a0afadc2d7..7727a630dd 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -2379,26 +2379,37 @@ Mutability @section Mutability @cindex mutable objects =20 - Some Lisp objects should never change. For example, you can create -a new number by calculating one, but you cannot modify the value of an -existing number. + Some Lisp objects should never change. For example, the Lisp +expression @code{"aaa"} yields a string, but you should not change +its contents. Indeed, some objects cannot be changed; for example, +although you can create a new number by calculating one, Lisp provides +no operation to change the value of an existing number. =20 Other Lisp objects are @dfn{mutable}: it is safe to change their values via destructive operations involving side effects. For example, an existing marker can be changed by moving the marker to point to somewhere else. =20 - Although numbers never change and all markers are mutable, a type -can be a hybrid with some members mutable and other members not. These -types include conses, vectors, strings, and symbols. For example, the s= tring -literal @code{"aaa"} yields a string that should not be changed, whereas= the -call @code{(make-string 3 ?a)} yields a mutable string that can be + Although numbers never change and all markers are mutable, +some types have members some of which are mutable and others not. These +types include conses, vectors, strings, and symbols. For example, +although @code{"aaa"} yields a string that should not be changed, +@code{(make-string 3 ?a)} yields a mutable string that can be changed via later calls to @code{aset}. =20 A mutable object stops being mutable if it is part of an expression -that is evaluated. For example, in @code{(eval (list 'quote (list 1)))} -the list @code{(1)} was mutable when it was created, but it should not -be changed after it was part of an argument to @code{eval}. The +that is evaluated. For example: + +@example +(let* ((x (list 0.5)) + (y (eval (list 'quote x)))) + (setcar x 1.5) ;; The program should not do this. + y) +@end example + +@noindent +Although the list @code{(0.5)} was mutable when it was created, it shoul= d not +have been changed via @code{setcar} because it given to @code{eval}. Th= e reverse does not occur: an object that should not be changed never becomes mutable afterwards. =20 --=20 2.17.1 --------------312F946E318346DC6D4AB88F Content-Type: text/x-patch; charset=UTF-8; name="0001-Don-t-use-constant-for-values-you-shouldn-t-change.patch" Content-Disposition: attachment; filename*0="0001-Don-t-use-constant-for-values-you-shouldn-t-change.patc"; filename*1="h" Content-Transfer-Encoding: quoted-printable >From 1ddbbfd38c280822d1bed3c1281909fbfea1f54f Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Sun, 10 May 2020 09:27:02 -0700 Subject: [PATCH] =3D?UTF-8?q?Don=3DE2=3D80=3D99t=3D20use=3D20=3DE2=3D80=3D= 9Cconstant?=3D =3D?UTF-8?q?=3DE2=3D80=3D9D=3D20for=3D20values=3D20you=3D20shouldn=3DE2=3D= 80=3D99t=3D20change?=3D MIME-Version: 1.0 Content-Type: text/plain; charset=3DUTF-8 Content-Transfer-Encoding: 8bit Inspired by patch proposed by Dmitry Gutov (Bug#40671#393) and by his further comments (Bug#40671#420). * doc/lispintro/emacs-lisp-intro.texi (setcar): Don=E2=80=99t push mutability here. * doc/lispref/eval.texi (Self-Evaluating Forms, Quoting) (Backquote): * doc/lispref/lists.texi (Modifying Lists): * doc/lispref/objects.texi (Lisp Data Types, Mutability): * doc/lispref/sequences.texi (Array Functions, Vectors): * doc/lispref/strings.texi (String Basics, Modifying Strings): Don=E2=80=99t use the word =E2=80=9Cconstant=E2=80=9D to describe all val= ues that a program should not change. * doc/lispref/objects.texi (Mutability): Rename from =E2=80=9CConstants and Mutability=E2=80=9D. All uses changed= . In a footnote, contrast the Emacs behavior with that of Common Lisp, Python, etc. for clarity, and say the goal is to be nicer. Update mutability doc * doc/lispref/objects.texi (Mutability): Revise in response to Dmitry Gutov=E2=80=99s comments (Bug#40671#420). --- doc/lispintro/emacs-lisp-intro.texi | 5 +- doc/lispref/elisp.texi | 2 +- doc/lispref/eval.texi | 21 +++---- doc/lispref/lists.texi | 16 ++--- doc/lispref/objects.texi | 90 +++++++++++++++-------------- doc/lispref/sequences.texi | 25 ++++---- doc/lispref/strings.texi | 11 ++-- 7 files changed, 83 insertions(+), 87 deletions(-) diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-li= sp-intro.texi index ea16d9ef15..46462162ca 100644 --- a/doc/lispintro/emacs-lisp-intro.texi +++ b/doc/lispintro/emacs-lisp-intro.texi @@ -7317,8 +7317,6 @@ setcar works is to experiment. We will start with the @code{setcar} function. =20 @need 1200 -@cindex constant lists -@cindex mutable lists First, we can make a list and then set the value of a variable to the list, using the @code{setq} special form. Because we intend to use @code{setcar} to change the list, this @code{setq} should not use the @@ -7327,8 +7325,7 @@ setcar tried to change part of the program while running it. Generally speaking an Emacs Lisp program's components should be constant (or unchanged) while the program is running. So we instead construct an -animal list that is @dfn{mutable} (or changeable) by using the -@code{list} function, as follows: +animal list by using the @code{list} function, as follows: =20 @smallexample (setq animals (list 'antelope 'giraffe 'lion 'tiger)) diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index bba1b63115..9a6796790c 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -297,7 +297,7 @@ Top * Circular Objects:: Read syntax for circular structure. * Type Predicates:: Tests related to types. * Equality Predicates:: Tests of equality between any two objects. -* Constants and Mutability:: Whether an object's value can change. +* Mutability:: Some objects should not be modified. =20 Programming Types =20 diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi index baddce4d9c..39f342a798 100644 --- a/doc/lispref/eval.texi +++ b/doc/lispref/eval.texi @@ -158,11 +158,11 @@ Self-Evaluating Forms @end group @end example =20 - A self-evaluating form yields constant conses, vectors and strings, an= d you -should not attempt to modify their contents via @code{setcar}, @code{ase= t} or + A self-evaluating form yields a value that becomes part of the program= , +and you should not try to modify it via @code{setcar}, @code{aset} or similar operations. The Lisp interpreter might unify the constants yielded by your program's self-evaluating forms, so that these -constants might share structure. @xref{Constants and Mutability}. +constants might share structure. @xref{Mutability}. =20 It is common to write numbers, characters, strings, and even vectors in Lisp code, taking advantage of the fact that they self-evaluate. @@ -564,8 +564,8 @@ Quoting =20 @defspec quote object This special form returns @var{object}, without evaluating it. -The returned value is a constant, and should not be modified. -@xref{Constants and Mutability}. +The returned value might be shared and should not be modified. +@xref{Self-Evaluating Forms}. @end defspec =20 @cindex @samp{'} for quoting @@ -608,9 +608,9 @@ Quoting =20 Although the expressions @code{(list '+ 1 2)} and @code{'(+ 1 2)} both yield lists equal to @code{(+ 1 2)}, the former yields a -freshly-minted mutable list whereas the latter yields a constant list -built from conses that may be shared with other constants. -@xref{Constants and Mutability}. +freshly-minted mutable list whereas the latter yields a list +built from conses that might be shared and should not be modified. +@xref{Self-Evaluating Forms}. =20 Other quoting constructs include @code{function} (@pxref{Anonymous Functions}), which causes an anonymous lambda expression written in Lisp @@ -710,8 +710,9 @@ Backquote @end example =20 If a subexpression of a backquote construct has no substitutions or -splices, it acts like @code{quote} in that it yields constant conses, -vectors and strings that should not be modified. +splices, it acts like @code{quote} in that it yields conses, +vectors and strings that might be shared and should not be modified. +@xref{Self-Evaluating Forms}. =20 @node Eval @section Eval diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi index fcaf4386b1..ae793d5e15 100644 --- a/doc/lispref/lists.texi +++ b/doc/lispref/lists.texi @@ -873,8 +873,8 @@ Modifying Lists operations because they change existing list structure. Destructive operations should be applied only to mutable lists, that is, lists constructed via @code{cons}, @code{list} or similar -operations. Lists created by quoting are constants and should not be -changed by destructive operations. @xref{Constants and Mutability}. +operations. Lists created by quoting are part of the program and +should not be changed by destructive operations. @xref{Mutability}. =20 @cindex CL note---@code{rplaca} vs @code{setcar} @quotation @@ -911,7 +911,7 @@ Setcar =20 @example @group -(setq x (list 1 2)) ; @r{Create a mutable list.} +(setq x (list 1 2)) @result{} (1 2) @end group @group @@ -931,7 +931,7 @@ Setcar =20 @example @group -;; @r{Create two mutable lists that are partly shared.} +;; @r{Create two lists that are partly shared.} (setq x1 (list 'a 'b 'c)) @result{} (a b c) (setq x2 (cons 'z (cdr x1))) @@ -1022,11 +1022,11 @@ Setcdr =20 @example @group -(setq x (list 1 2 3)) ; @r{Create a mutable list.} +(setq x (list 1 2 3)) @result{} (1 2 3) @end group @group -(setcdr x '(4)) ; @r{Modify the list's tail to be a constant list.} +(setcdr x '(4)) @result{} (4) @end group @group @@ -1135,11 +1135,11 @@ Rearrangement =20 @example @group -(setq x (list 1 2 3)) ; @r{Create a mutable list.} +(setq x (list 1 2 3)) @result{} (1 2 3) @end group @group -(nconc x '(4 5)) ; @r{Modify the list's tail to be a constant list.} +(nconc x '(4 5)) @result{} (1 2 3 4 5) @end group @group diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index 1d5b2c690f..7727a630dd 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -46,10 +46,6 @@ Lisp Data Types Lisp variables can only take on values of a certain type. @xref{Variables with Restricted Values}.) =20 - Some Lisp objects are @dfn{constant}: their values should never change= . -Others are @dfn{mutable}: their values can be changed via destructive -operations that involve side effects. - This chapter describes the purpose, printed representation, and read syntax of each of the standard types in GNU Emacs Lisp. Details on how to use these types can be found in later chapters. @@ -63,7 +59,7 @@ Lisp Data Types * Circular Objects:: Read syntax for circular structure. * Type Predicates:: Tests related to types. * Equality Predicates:: Tests of equality between any two object= s. -* Constants and Mutability:: Whether an object's value can change. +* Mutability:: Some objects should not be modified. @end menu =20 @node Printed Representation @@ -2379,51 +2375,59 @@ Equality Predicates @end example @end defun =20 -@node Constants and Mutability -@section Constants and Mutability -@cindex constants +@node Mutability +@section Mutability @cindex mutable objects =20 - Some Lisp objects are constant: their values should never change -during a single execution of Emacs running well-behaved Lisp code. -For example, you can create a new integer by calculating one, but you -cannot modify the value of an existing integer. - - Other Lisp objects are mutable: it is safe to change their values -via destructive operations involving side effects. For example, an -existing marker can be changed by moving the marker to point to -somewhere else. - - Although all numbers are constants and all markers are -mutable, some types contain both constant and mutable members. These -types include conses, vectors, strings, and symbols. For example, the s= tring -literal @code{"aaa"} yields a constant string, whereas the function -call @code{(make-string 3 ?a)} yields a mutable string that can be + Some Lisp objects should never change. For example, the Lisp +expression @code{"aaa"} yields a string, but you should not change +its contents. Indeed, some objects cannot be changed; for example, +although you can create a new number by calculating one, Lisp provides +no operation to change the value of an existing number. + + Other Lisp objects are @dfn{mutable}: it is safe to change their +values via destructive operations involving side effects. For +example, an existing marker can be changed by moving the marker to +point to somewhere else. + + Although numbers never change and all markers are mutable, +some types have members some of which are mutable and others not. These +types include conses, vectors, strings, and symbols. For example, +although @code{"aaa"} yields a string that should not be changed, +@code{(make-string 3 ?a)} yields a mutable string that can be changed via later calls to @code{aset}. =20 - A mutable object can become constant if it is part of an expression -that is evaluated. The reverse does not occur: constant objects -should stay constant. + A mutable object stops being mutable if it is part of an expression +that is evaluated. For example: + +@example +(let* ((x (list 0.5)) + (y (eval (list 'quote x)))) + (setcar x 1.5) ;; The program should not do this. + y) +@end example + +@noindent +Although the list @code{(0.5)} was mutable when it was created, it shoul= d not +have been changed via @code{setcar} because it given to @code{eval}. Th= e +reverse does not occur: an object that should not be changed never +becomes mutable afterwards. =20 Trying to modify a constant variable signals an error (@pxref{Constant Variables}). -A program should not attempt to modify other types of constants because = the -resulting behavior is undefined: the Lisp interpreter might or might -not detect the error, and if it does not detect the error the -interpreter can behave unpredictably thereafter. Another way to put -this is that although mutable objects are safe to change and constant -variables reliably prevent attempts to change them, other constants -are not safely mutable: if a misbehaving program tries to change such a -constant then the constant's value might actually change, or the -program might crash or worse. This problem occurs -with types that have both constant and mutable members, and that have -mutators like @code{setcar} and @code{aset} that are valid on mutable -objects but hazardous on constants. - - When the same constant occurs multiple times in a program, the Lisp -interpreter might save time or space by reusing existing constants or -constant components. For example, @code{(eq "abc" "abc")} returns +If a program attempts to change other objects that should not be +changed, the resulting behavior is undefined: the Lisp interpreter +might signal an error, or it might crash or behave unpredictably in +other ways.@footnote{This is the behavior specified for languages like +Common Lisp and C, and it differs from the behavior of languages like +JavaScript and Python where an interpreter is required to signal an +error if a program attempts to change a constant. Ideally the Emacs +Lisp interpreter will evolve in latter direction.} + + When the same value appears multiple times in a program, the Lisp +interpreter might save time or space by reusing existing values or +their components. For example, @code{(eq "abc" "abc")} returns @code{t} if the interpreter creates only one instance of the string -constant @code{"abc"}, and returns @code{nil} if it creates two +literal @code{"abc"}, and returns @code{nil} if it creates two instances. Lisp programs should be written so that they work regardless of whether this optimization is in use. diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi index 1cb0d05cc7..91c3049f87 100644 --- a/doc/lispref/sequences.texi +++ b/doc/lispref/sequences.texi @@ -183,11 +183,11 @@ Sequence Functions =20 @example @group -(setq bar (list 1 2)) ; @r{Create a mutable list.} +(setq bar (list 1 2)) @result{} (1 2) @end group @group -(setq x (vector 'foo bar)) ; @r{Create a mutable vector.} +(setq x (vector 'foo bar)) @result{} [foo (1 2)] @end group @group @@ -278,7 +278,7 @@ Sequence Functions =20 @example @group -(setq x (list 'a 'b 'c)) ; @r{Create a mutable list.} +(setq x (list 'a 'b 'c)) @result{} (a b c) @end group @group @@ -320,7 +320,7 @@ Sequence Functions For the vector, it is even simpler because you don't need setq: =20 @example -(setq x (copy-sequence [1 2 3 4])) ; @r{Create a mutable vector.} +(setq x (copy-sequence [1 2 3 4])) @result{} [1 2 3 4] (nreverse x) @result{} [4 3 2 1] @@ -331,6 +331,7 @@ Sequence Functions Note that unlike @code{reverse}, this function doesn't work with strings= . Although you can alter string data by using @code{aset}, it is strongly encouraged to treat strings as immutable even when they are mutable. +@xref{Mutability}. =20 @end defun =20 @@ -374,7 +375,7 @@ Sequence Functions =20 @example @group -(setq nums (list 1 3 2 6 5 4 0)) ; @r{Create a mutable list.} +(setq nums (list 1 3 2 6 5 4 0)) @result{} (1 3 2 6 5 4 0) @end group @group @@ -1228,7 +1229,7 @@ Array Functions =20 @example @group -(setq w (vector 'foo 'bar 'baz)) ; @r{Create a mutable vector.} +(setq w (vector 'foo 'bar 'baz)) @result{} [foo bar baz] (aset w 0 'fu) @result{} fu @@ -1237,7 +1238,7 @@ Array Functions @end group =20 @group -;; @r{@code{copy-sequence} creates a mutable string.} +;; @r{@code{copy-sequence} copies the string to be modified later.} (setq x (copy-sequence "asdfasfd")) @result{} "asdfasfd" (aset x 3 ?Z) @@ -1247,9 +1248,7 @@ Array Functions @end group @end example =20 -The @var{array} should be mutable; that is, it should not be a constant, -such as the constants created via quoting or via self-evaluating forms. -@xref{Constants and Mutability}. +The @var{array} should be mutable. @xref{Mutability}. =20 If @var{array} is a string and @var{object} is not a character, a @code{wrong-type-argument} error results. The function converts a @@ -1262,7 +1261,6 @@ Array Functions =20 @example @group -;; @r{Create a mutable vector and then fill it with zeros.} (setq a (copy-sequence [a b c d e f g])) @result{} [a b c d e f g] (fillarray a 0) @@ -1271,7 +1269,6 @@ Array Functions @result{} [0 0 0 0 0 0 0] @end group @group -;; @r{Create a mutable string and then fill it with "-".} (setq s (copy-sequence "When in the course")) @result{} "When in the course" (fillarray s ?-) @@ -1310,8 +1307,8 @@ Vectors evaluation: the result of evaluating it is the same vector. This does not evaluate or even examine the elements of the vector. @xref{Self-Evaluating Forms}. Vectors written with square brackets -are constants and should not be modified via @code{aset} or other -destructive operations. @xref{Constants and Mutability}. +should not be modified via @code{aset} or other destructive +operations. @xref{Mutability}. =20 Here are examples illustrating these principles: =20 diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index a4c9c2549c..70c3b3cf4b 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -49,10 +49,9 @@ String Basics =20 Since strings are arrays, and therefore sequences as well, you can operate on them with the general array and sequence functions documented -in @ref{Sequences Arrays Vectors}. For example, you can access or -change individual characters in a string using the functions @code{aref} -and @code{aset} (@pxref{Array Functions}). However, you should not -try to change the contents of constant strings (@pxref{Modifying Strings= }). +in @ref{Sequences Arrays Vectors}. For example, you can access +individual characters in a string using the function @code{aref} +(@pxref{Array Functions}). =20 There are two text representations for non-@acronym{ASCII} characters in Emacs strings (and in buffers): unibyte and multibyte. @@ -382,9 +381,7 @@ Modifying Strings @cindex string modification =20 You can alter the contents of a mutable string via operations -described in this section. However, you should not try to use these -operations to alter the contents of a constant string. -@xref{Constants and Mutability}. +described in this section. @xref{Mutability}. =20 The most basic way to alter the contents of an existing string is with @code{aset} (@pxref{Array Functions}). @code{(aset @var{string} --=20 2.17.1 --------------312F946E318346DC6D4AB88F--