Commit 5805df74 authored by Paul Eggert's avatar Paul Eggert

Improve mutability doc

See Eli Zaretskii’s suggestions (Bug#40671#33).
* doc/lispref/lists.texi (Setcar, Setcdr, Rearrangement):
* doc/lispref/sequences.texi (Sequence Functions)
(Array Functions):
Add commentary to examples.
* doc/lispref/lists.texi (Sets And Lists):
Revert change to delq example.
parent dca35b31
Pipeline #5321 passed with stage
in 61 minutes and 10 seconds
......@@ -911,7 +911,7 @@ value @var{object}. For example:
@example
@group
(setq x (list 1 2))
(setq x (list 1 2)) ; @r{Create a mutable list.}
@result{} (1 2)
@end group
@group
......@@ -931,7 +931,7 @@ these lists. Here is an example:
@example
@group
;; @r{Create two lists that are partly shared.}
;; @r{Create two mutable 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 @@ reached via the @sc{cdr}.
@example
@group
(setq x (list 1 2 3))
(setq x (list 1 2 3)) ; @r{Create a mutable list.}
@result{} (1 2 3)
@end group
@group
(setcdr x '(4))
(setcdr x '(4)) ; @r{Modify the list's tail to be a constant list.}
@result{} (4)
@end group
@group
......@@ -1135,11 +1135,11 @@ Unlike @code{append} (@pxref{Building Lists}), the @var{lists} are
@example
@group
(setq x (list 1 2 3))
(setq x (list 1 2 3)) ; @r{Create a mutable list.}
@result{} (1 2 3)
@end group
@group
(nconc x '(4 5))
(nconc x '(4 5)) ; @r{Modify the list's tail to be a constant list.}
@result{} (1 2 3 4 5)
@end group
@group
......@@ -1267,9 +1267,7 @@ after those elements. For example:
@example
@group
(equal
(delq 'a (list 'a 'b 'c))
(cdr (list 'a 'b 'c)))
(delq 'a '(a b c)) @equiv{} (cdr '(a b c))
@end group
@end example
......
......@@ -183,11 +183,11 @@ for other ways to copy sequences.
@example
@group
(setq bar (list 1 2))
(setq bar (list 1 2)) ; @r{Create a mutable list.}
@result{} (1 2)
@end group
@group
(setq x (vector 'foo bar))
(setq x (vector 'foo bar)) ; @r{Create a mutable vector.}
@result{} [foo (1 2)]
@end group
@group
......@@ -278,7 +278,7 @@ Unlike @code{reverse} the original @var{sequence} may be modified.
@example
@group
(setq x (list 'a 'b 'c))
(setq x (list 'a 'b 'c)) ; @r{Create a mutable list.}
@result{} (a b c)
@end group
@group
......@@ -320,7 +320,7 @@ presented graphically:
For the vector, it is even simpler because you don't need setq:
@example
(setq x (copy-sequence [1 2 3 4]))
(setq x (copy-sequence [1 2 3 4])) ; @r{Create a mutable vector.}
@result{} [1 2 3 4]
(nreverse x)
@result{} [4 3 2 1]
......@@ -374,7 +374,7 @@ appears in a different position in the list due to the change of
@example
@group
(setq nums (list 1 3 2 6 5 4 0))
(setq nums (list 1 3 2 6 5 4 0)) ; @r{Create a mutable list.}
@result{} (1 3 2 6 5 4 0)
@end group
@group
......@@ -1228,7 +1228,7 @@ This function sets the @var{index}th element of @var{array} to be
@example
@group
(setq w (vector 'foo 'bar 'baz))
(setq w (vector 'foo 'bar 'baz)) ; @r{Create a mutable vector.}
@result{} [foo bar baz]
(aset w 0 'fu)
@result{} fu
......@@ -1262,6 +1262,7 @@ each element of @var{array} is @var{object}. It returns @var{array}.
@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)
......@@ -1270,6 +1271,7 @@ a
@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 ?-)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment