Altering List Elements with setcar

Changing the CAR of a cons cell is done with setcar. When used on a list, setcar replaces one element of a list with a different element.

Function: setcar cons object

This function stores object as the new CAR of cons, replacing its previous CAR. It returns the value object. For example:

(setq x '(1 2))
     => (1 2)
(setcar x 4)
     => 4
x
     => (4 2)

When a cons cell is part of the shared structure of several lists, storing a new CAR into the cons changes one element of each of these lists. Here is an example:

;; Create two lists that are partly shared.
(setq x1 '(a b c))
     => (a b c)
(setq x2 (cons 'z (cdr x1)))
     => (z b c)

;; Replace the CAR of a shared link.
(setcar (cdr x1) 'foo)
     => foo
x1                           ; Both lists are changed.
     => (a foo c)
x2
     => (z foo c)

;; Replace the CAR of a link that is not shared.
(setcar x1 'baz)
     => baz
x1                           ; Only one list is changed.
     => (baz foo c)
x2
     => (z foo c)

Here is a graphical depiction of the shared structure of the two lists in the variables x1 and x2, showing why replacing b changes them both:

        ___ ___        ___ ___      ___ ___
x1---> |___|___|----> |___|___|--> |___|___|--> nil
         |        -->   |            |
         |       |      |            |
          --> a  |       --> b        --> c
                 |
       ___ ___   |
x2--> |___|___|--
        |
        |
         --> z

Here is an alternative form of box diagram, showing the same relationship:

x1:
 --------------       --------------       --------------
| car   | cdr  |     | car   | cdr  |     | car   | cdr  |
|   a   |   o------->|   b   |   o------->|   c   |  nil |
|       |      |  -->|       |      |     |       |      |
 --------------  |    --------------       --------------
                 |
x2:              |
 --------------  |
| car   | cdr  | |
|   z   |   o----
|       |      |
 --------------

Go to the first, previous, next, last section, table of contents.