10.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 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 cars and cdrs 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.