new repository

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>&amp;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 &copy; 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>