diff options
| author | Craig Jennings <c@cjennings.net> | 2024-04-07 13:41:34 -0500 |
|---|---|---|
| committer | Craig Jennings <c@cjennings.net> | 2024-04-07 13:41:34 -0500 |
| commit | 754bbf7a25a8dda49b5d08ef0d0443bbf5af0e36 (patch) | |
| tree | f1190704f78f04a2b0b4c977d20fe96a828377f1 /devdocs/elisp/setcar.html | |
new repository
Diffstat (limited to 'devdocs/elisp/setcar.html')
| -rw-r--r-- | devdocs/elisp/setcar.html | 70 |
1 files changed, 70 insertions, 0 deletions
diff --git a/devdocs/elisp/setcar.html b/devdocs/elisp/setcar.html new file mode 100644 index 00000000..67867eb1 --- /dev/null +++ b/devdocs/elisp/setcar.html @@ -0,0 +1,70 @@ + <h4 class="subsection">Altering List Elements with setcar</h4> <p>Changing the <small>CAR</small> of a cons cell is done with <code>setcar</code>. When used on a list, <code>setcar</code> replaces one element of a list with a different element. </p> <dl> <dt id="setcar">Function: <strong>setcar</strong> <em>cons object</em> +</dt> <dd> +<p>This function stores <var>object</var> as the new <small>CAR</small> of <var>cons</var>, replacing its previous <small>CAR</small>. In other words, it changes the <small>CAR</small> slot of <var>cons</var> to refer to <var>object</var>. It returns the value <var>object</var>. For example: </p> <div class="example"> <pre class="example">(setq x (list 1 2)) + ⇒ (1 2) +</pre> +<pre class="example">(setcar x 4) + ⇒ 4 +</pre> +<pre class="example">x + ⇒ (4 2) +</pre> +</div> </dd> +</dl> <p>When a cons cell is part of the shared structure of several lists, storing a new <small>CAR</small> into the cons changes one element of each of these lists. Here is an example: </p> <div class="example"> <pre class="example">;; <span class="roman">Create two lists that are partly shared.</span> +(setq x1 (list 'a 'b 'c)) + ⇒ (a b c) +(setq x2 (cons 'z (cdr x1))) + ⇒ (z b c) +</pre> + +<pre class="example">;; <span class="roman">Replace the CAR of a shared link.</span> +(setcar (cdr x1) 'foo) + ⇒ foo +x1 ; <span class="roman">Both lists are changed.</span> + ⇒ (a foo c) +x2 + ⇒ (z foo c) +</pre> + +<pre class="example">;; <span class="roman">Replace the CAR of a link that is not shared.</span> +(setcar x1 'baz) + ⇒ baz +x1 ; <span class="roman">Only one list is changed.</span> + ⇒ (baz foo c) +x2 + ⇒ (z foo c) +</pre> +</div> <p>Here is a graphical depiction of the shared structure of the two lists in the variables <code>x1</code> and <code>x2</code>, showing why replacing <code>b</code> changes them both: </p> <div class="example"> <pre class="example"> --- --- --- --- --- --- +x1---> | | |----> | | |--> | | |--> nil + --- --- --- --- --- --- + | --> | | + | | | | + --> a | --> b --> c + | + --- --- | +x2--> | | |-- + --- --- + | + | + --> z +</pre> +</div> <p>Here is an alternative form of box diagram, showing the same relationship: </p> <div class="example"> <pre class="example">x1: + -------------- -------------- -------------- +| car | cdr | | car | cdr | | car | cdr | +| a | o------->| b | o------->| c | nil | +| | | -->| | | | | | + -------------- | -------------- -------------- + | +x2: | + -------------- | +| car | cdr | | +| z | o---- +| | | + -------------- +</pre> +</div><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/Setcar.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Setcar.html</a> + </p> +</div> |