### 10.2 Substitution of Expressions

These functions substitute elements throughout a tree of cons
cells. (See Sequence Functions, for the `cl-substitute`

function, which works on just the top-level elements of a list.)

- Function:
**cl-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 CARs and CDRs
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:
**cl-nsubst** `new old tree ``&key :test :test-not :key`

¶
This function is like `cl-subst`

, except that it works by
destructive modification (by `setcar`

or `setcdr`

)
rather than copying.

The `cl-subst-if`

, `cl-subst-if-not`

, `cl-nsubst-if`

, and
`cl-nsubst-if-not`

functions are defined similarly.

- Function:
**cl-sublis** `alist tree ``&key :test :test-not :key`

¶
This function is like `cl-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 CARs of
`alist`; if it matches, it is replaced by the corresponding
CDR.

- Function:
**cl-nsublis** `alist tree ``&key :test :test-not :key`

¶
This is a destructive version of `cl-sublis`

.