Next: Setcdr, Up: Modifying Lists [Contents][Index]

#### 5.6.1 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. In other words, it changes the CAR slot of cons to refer to object. 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----
    |       |      |
     --------------

Next: Setcdr, Up: Modifying Lists [Contents][Index]