Next: Substitution of Expressions, Previous: Lists, Up: Lists

### 11.1 List Functions

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

— Function: caddr x

> This function is equivalent to `(car (cdr (cdr` x`)))`. Likewise, this package defines all 28 `c` xxx `r` 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: 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.