(lispref.info)Setcar


Next: Setcdr Prev: Modifying Lists Up: Modifying Lists

Altering List Elements with `setcar'
------------------------------------

   Changing the CAR of a cons cell is done with `setcar' and 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 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----
     |       |      |
      --------------


automatically generated by info2www