From 754bbf7a25a8dda49b5d08ef0d0443bbf5af0e36 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Sun, 7 Apr 2024 13:41:34 -0500 Subject: new repository --- devdocs/elisp/rearrangement.html | 48 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 devdocs/elisp/rearrangement.html (limited to 'devdocs/elisp/rearrangement.html') diff --git a/devdocs/elisp/rearrangement.html b/devdocs/elisp/rearrangement.html new file mode 100644 index 00000000..b82bf73e --- /dev/null +++ b/devdocs/elisp/rearrangement.html @@ -0,0 +1,48 @@ +

Functions that Rearrange Lists

Here are some functions that rearrange lists destructively by modifying the CDRs of their component cons cells. These functions are destructive because they chew up the original lists passed to them as arguments, relinking their cons cells to form a new list that is the returned value.

See delq, in Sets And Lists, for another function that modifies cons cells.

Function: nconc &rest lists +
+

This function returns a list containing all the elements of lists. Unlike append (see Building Lists), the lists are not copied. Instead, the last CDR of each of the lists is changed to refer to the following list. The last of the lists is not altered. For example: 

(setq x (list 1 2 3))
+     ⇒ (1 2 3)
+
+
(nconc x '(4 5))
+     ⇒ (1 2 3 4 5)
+
+
x
+     ⇒ (1 2 3 4 5)
+
+

Since the last argument of nconc is not itself modified, it is reasonable to use a constant list, such as '(4 5), as in the above example. For the same reason, the last argument need not be a list: 

(setq x (list 1 2 3))
+     ⇒ (1 2 3)
+
+
(nconc x 'z)
+     ⇒ (1 2 3 . z)
+
+
x
+     ⇒ (1 2 3 . z)
+
+

However, the other arguments (all but the last) should be mutable lists.

A common pitfall is to use a constant list as a non-last argument to nconc. If you do this, the resulting behavior is undefined (see Self-Evaluating Forms). It is possible that your program will change each time you run it! Here is what might happen (though this is not guaranteed to happen): 

(defun add-foo (x)            ; We want this function to add
+  (nconc '(foo) x))           ;   foo to the front of its arg.
+
+ +
(symbol-function 'add-foo)
+     ⇒ (lambda (x) (nconc '(foo) x))
+
+ +
(setq xx (add-foo '(1 2)))    ; It seems to work.
+     ⇒ (foo 1 2)
+
+
(setq xy (add-foo '(3 4)))    ; What happened?
+     ⇒ (foo 1 2 3 4)
+
+
(eq xx xy)
+     ⇒ t
+
+ +
(symbol-function 'add-foo)
+     ⇒ (lambda (x) (nconc '(foo 1 2 3 4) x))
+
+
+
+

+ Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc.
Licensed under the GNU GPL license.
+ https://www.gnu.org/software/emacs/manual/html_node/elisp/Rearrangement.html +

+
-- cgit v1.2.3