Next: , Previous: , Up: Lists   [Contents][Index]

### 10.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 signalling 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))`.

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.

Next: , Previous: , Up: Lists   [Contents][Index]