Next:

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 `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. *Note Sequences::.