Common Lisp Extensions. Node: List Functions

## 11.1: List Functions

This section describes a number of simple operations on lists, i.e., chains of cons cells.

This function is equivalent to `(car (cdr (cdr x)))`. Likewise, this package defines all 28 `cxxxr` functions where xxx is up to four ``a`'s and/or ``d`'s. All of these functions are `setf`-able, and calls to them are expanded inline by the byte-compiler for maximum efficiency.
Function: first x
This function is a synonym for `(car x)`. Likewise, the functions `second`, `third`, ..., through `tenth` return the given element of the list x.
Function: rest x
This function is a synonym for `(cdr x)`.
Function: endp x
Common Lisp defines this function to act like `null`, but signaling an error if `x` is neither a `nil` nor a cons cell. This package simply defines `endp` as a synonym for `null`.
Function: list-length x
This function returns the length of list x, exactly like `(length x)`, except that if x is a circular list (where the cdr-chain forms a loop rather than terminating with `nil`), this function returns `nil`. (The regular `length` function would get stuck if given a circular list.)
Function: last* x &optional n
This function returns the last cons, or the nth-to-last cons, of the list x. If n is omitted it defaults to 1. The ``last cons'' means the first cons cell of the list whose `cdr` is not another cons cell. (For normal lists, the `cdr` of the last cons will be `nil`.) This function returns `nil` if x is `nil` or shorter than n. Note that the last element of the list is `(car (last x))`.

The Emacs function `last` does the same thing except that it does not handle the optional argument n.

Function: butlast x &optional n
This function returns the list x with the last element, or the last n elements, removed. If n is greater than zero it makes a copy of the list so as not to damage the original list. In general, `(append (butlast x n) (last x n))` will return a list equal to x.
Function: nbutlast x &optional n
This is a version of `butlast` that works by destructively modifying the `cdr` of the appropriate element, rather than making a copy of the list.
Function: list* arg &rest others
This function constructs a list of its arguments. The final argument becomes the `cdr` of the last cell constructed. Thus, `(list* a b c)` is equivalent to `(cons a (cons b c))`, and `(list* a b nil)` is equivalent to `(list a b)`.

(Note that this function really is called `list*` in Common Lisp; it is not a name invented for this package like `member*` or `defun*`.)

Function: ldiff list sublist
If sublist is a sublist of list, i.e., is `eq` to one of the cons cells of list, then this function returns a copy of the part of list up to but not including sublist. For example, `(ldiff x (cddr x))` returns the first two elements of the list `x`. The result is a copy; the original list is not modified. If sublist is not a sublist of list, a copy of the entire list is returned.
Function: copy-list list
This function returns a copy of the list list. It copies dotted lists like `(1 2 . 3)` correctly.
Function: copy-tree x &optional vecp
This function returns a copy of the tree of cons cells x. Unlike `copy-sequence` (and its alias `copy-list`), which copies only along the `cdr` direction, this function copies (recursively) along both the `car` and the `cdr` directions. If x is not a cons cell, the function simply returns x unchanged. If the optional vecp argument is true, this function copies vectors (recursively) as well as cons cells.
Function: tree-equal x y `&key :test :test-not :key`
This function compares two trees of cons cells. If x and y are both cons cells, their `car`s and `cdr`s are compared recursively. If neither x nor y is a cons cell, they are compared by `eql`, or according to the specified test. The `:key` function, if specified, is applied to the elements of both trees. See Sequences.
Lists Lists Substitution of Expressions