devdocs/elisp/setcar.html


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
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---&gt; |   |   |----&gt; |   |   |--&gt; |   |   |--&gt; nil
        --- ---        --- ---      --- ---
         |        --&gt;   |            |
         |       |      |            |
          --&gt; a  |       --&gt; b        --&gt; c
                 |
       --- ---   |
x2--&gt; |   |   |--
       --- ---
        |
        |
         --&gt; 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-------&gt;|   b   |   o-------&gt;|   c   |  nil |
|       |      |  --&gt;|       |      |     |       |      |
 --------------  |    --------------       --------------
                 |
x2:              |
 --------------  |
| car   | cdr  | |
|   z   |   o----
|       |      |
 --------------
</pre>
</div><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/Setcar.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Setcar.html</a>
  </p>
</div>