Next: Lists as Sets, Previous: List Functions, Up: Lists

### 11.2 Substitution of Expressions

These functions substitute elements throughout a tree of cons cells. (See Sequence Functions, for the `substitute` function, which works on just the top-level elements of a list.)

— Function: subst new old tree `&key :test :test-not :key`

> This function substitutes occurrences of old with new in tree, a tree of cons cells. It returns a substituted tree, which will be a copy except that it may share storage with the argument tree in parts where no substitutions occurred. The original tree is not modified. This function recurses on, and compares against old, both `car`s and `cdr`s of the component cons cells. If old is itself a cons cell, then matching cells in the tree are substituted as usual without recursively substituting in that cell. Comparisons with old are done according to the specified test (`eql` by default). The `:key` function is applied to the elements of the tree but not to old.

— Function: nsubst new old tree `&key :test :test-not :key`

> This function is like `subst`, except that it works by destructive modification (by `setcar` or `setcdr`) rather than copying.

The `subst-if`, `subst-if-not`, `nsubst-if`, and `nsubst-if-not` functions are defined similarly.

— Function: sublis alist tree `&key :test :test-not :key`

> This function is like `subst`, except that it takes an association list alist of old-new pairs. Each element of the tree (after applying the `:key` function, if any), is compared with the `car`s of alist; if it matches, it is replaced by the corresponding `cdr`.

— Function: nsublis alist tree `&key :test :test-not :key`

> This is a destructive version of `sublis`.