GNU Info

(librep.info)Modifying Lists

---

Next: Association Lists Prev: Accessing List Elements Up: Lists

---

Enter node , (file) or (file)node

Modifying Lists
...............

   The `nthcdr' function can be used in conjunction with the `rplaca'
function to modify an arbitrary element in a list. For example,

     (rplaca (nthcdr 2 '(0 1 2 3 4 5)) 'foo)
         => foo

sets the third element of the list `(0 1 2 3 4 5)' to the symbol called
`foo'.

   There are also functions which modify the structure of a whole list.
These are called "destructive" operations because they modify the actual
structure of a list--no copy is made. This can lead to unpleasant side
effects if care is not taken.

 - Function: nconc #!rest lists
     This function is the destructive equivalent of the function
     `append', it modifies its arguments so that it can return a list
     which is the concatenation of the elements in its arguments lists.

     Like all the destructive functions this means that the lists given
     as arguments are modified (specifically, the cdr of their last
     cons cell is made to point to the next list). This can be seen
     with the following example (similar to the example in the `append'
     documentation).

          (setq foo '(1 2))
              => (1 2)
          (setq bar '(3 4))
              => (3 4)
          (setq baz (nconc foo bar))
              => (1 2 3 4)
          foo
              => (1 2 3 4)                ;`foo' has been altered!
          (eq (nthcdr 2 baz) bar)
              => t

     The following diagram shows the final state of the three variables
     more clearly,

          foo-->                           bar-->
          baz--> +-----+-----+   +-----+-----+   +-----+-----+   +-----+-----+
                 |  o  |  o----> |  o  |  o----> |  o  |  o----> |  o  |     |
                 +--|--+-----+   +--|--+-----+   +--|--+-----+   +--|--+-----+
                    |               |               |               |
                     --> 1           --> 2             --> 3           --> 4

 - Function: nreverse list
     This function rearranges the cons cells constituting the list LIST
     so that the elements are in the reverse order to what they were.

          (setq foo '(1 2 3))
              => (1 2 3)
          (nreverse foo)
              => (3 2 1)
          foo
              => (1)                      ;`foo' wasn't updated when the list
                                          ; was altered.

 - Function: delete object list
     This function destructively removes all elements of the list LIST
     which are `equal' to OBJECT then returns the modified list.

          (delete 1 '(0 1 0 1 0))
              => (0 0 0)

     When this function is used to remove an element from a list which
     is stored in a variable that variable must be set to the return
     value of the `delete' function. Otherwise, if the first element of
     the list has to be deleted (because it is `equal' to OBJECT) the
     value of the variable will not change.

          (setq foo '(1 2 3))
              => (1 2 3)
          (delete 1 foo)
              => (2 3)
          foo
              => (1 2 3)
          (setq foo (delete 1 foo))
              => (2 3)

 - Function: delq object list
     This function is similar to the `delete' function, the only
     difference is that the `eq' function is used to compare OBJECT
     with each of the elements in LIST, instead of the `equal' function
     which is used by `delete'.

 - Function: sort list #!optional predicate
     Destructively sorts (i.e. by modifying cdrs) the list of values
     LIST, to satisfy the function PREDICATE, returning the sorted
     list. If PREDICATE is undefined, the `<' function is used, sorting
     the list into ascending order.

     PREDICATE is called with two values, it should return true if the
     first is considered less than the second.

          (sort '(5 3 7 4))
              => (3 4 5 7)

     The sort is stable, in that elements in the list which are equal
     will preserve their original positions in relation to each other.