diff options
Diffstat (limited to 'devdocs/elisp/rearrangement.html')
| -rw-r--r-- | devdocs/elisp/rearrangement.html | 48 |
1 files changed, 48 insertions, 0 deletions
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 @@ + <h4 class="subsection">Functions that Rearrange Lists</h4> <p>Here are some functions that rearrange lists destructively by modifying the <small>CDR</small>s 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. </p> <p>See <code>delq</code>, in <a href="sets-and-lists">Sets And Lists</a>, for another function that modifies cons cells. </p> <dl> <dt id="nconc">Function: <strong>nconc</strong> <em>&rest lists</em> +</dt> <dd> + <p>This function returns a list containing all the elements of <var>lists</var>. Unlike <code>append</code> (see <a href="building-lists">Building Lists</a>), the <var>lists</var> are <em>not</em> copied. Instead, the last <small>CDR</small> of each of the <var>lists</var> is changed to refer to the following list. The last of the <var>lists</var> is not altered. For example: </p> <div class="example"> <pre class="example">(setq x (list 1 2 3)) + ⇒ (1 2 3) +</pre> +<pre class="example">(nconc x '(4 5)) + ⇒ (1 2 3 4 5) +</pre> +<pre class="example">x + ⇒ (1 2 3 4 5) +</pre> +</div> <p>Since the last argument of <code>nconc</code> is not itself modified, it is reasonable to use a constant list, such as <code>'(4 5)</code>, as in the above example. For the same reason, the last argument need not be a list: </p> <div class="example"> <pre class="example">(setq x (list 1 2 3)) + ⇒ (1 2 3) +</pre> +<pre class="example">(nconc x 'z) + ⇒ (1 2 3 . z) +</pre> +<pre class="example">x + ⇒ (1 2 3 . z) +</pre> +</div> <p>However, the other arguments (all but the last) should be mutable lists. </p> <p>A common pitfall is to use a constant list as a non-last argument to <code>nconc</code>. If you do this, the resulting behavior is undefined (see <a href="self_002devaluating-forms">Self-Evaluating Forms</a>). 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): </p> <div class="example"> <pre class="example">(defun add-foo (x) ; <span class="roman">We want this function to add</span> + (nconc '(foo) x)) ; <span class="roman"><code>foo</code> to the front of its arg.</span> +</pre> + +<pre class="example">(symbol-function 'add-foo) + ⇒ (lambda (x) (nconc '(foo) x)) +</pre> + +<pre class="example">(setq xx (add-foo '(1 2))) ; <span class="roman">It seems to work.</span> + ⇒ (foo 1 2) +</pre> +<pre class="example">(setq xy (add-foo '(3 4))) ; <span class="roman">What happened?</span> + ⇒ (foo 1 2 3 4) +</pre> +<pre class="example">(eq xx xy) + ⇒ t +</pre> + +<pre class="example">(symbol-function 'add-foo) + ⇒ (lambda (x) (nconc '(foo 1 2 3 4) x)) +</pre> +</div> </dd> +</dl><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Rearrangement.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Rearrangement.html</a> + </p> +</div> |