The functions described here operate on lists.
This section describes a number of simple operations on lists, i.e., chains of cons cells.
(car (cdr (cdr x))). Likewise, this package defines all 28
cxxxrfunctions 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.
(car x). Likewise, the functions
third, ..., through
tenthreturn the given element of the list x.
null, but signaling an error if
xis neither a
nilnor a cons cell. This package simply defines
endpas a synonym for
(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
lengthfunction would get stuck if given a circular list.)
cdris not another cons cell. (For normal lists, the
cdrof the last cons will be
nil.) This function returns
nilif x is
nilor shorter than n. Note that the last element of the list is
(car (last x)).
(append (butlast x n) (last x n))will return a list equal to x.
butlastthat works by destructively modifying the
cdrof the appropriate element, rather than making a copy of the list.
cdrof 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
eqto 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.
(1 2 . 3)correctly.
copy-sequence(and its alias
copy-list), which copies only along the
cdrdirection, this function copies (recursively) along both the
cdrdirections. 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.
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
:keyfunction, if specified, is applied to the elements of both trees. See section Sequences.
These functions substitute elements throughout a tree of cons
cells. (See section Sequence Functions, for the
function, which works on just the top-level elements of a list.)
cdrs of the component cons cells. If old is itself a cons cell, then matching cells in the tree are substituted as usual without recursively substituting in that cell. Comparisons with old are done according to the specified test (
eqlby default). The
:keyfunction is applied to the elements of the tree but not to old.
subst, except that it works by destructive modification (by
setcdr) rather than copying.
nsubst-if-not functions are defined similarly.
subst, except that it takes an association list alist of old-new pairs. Each element of the tree (after applying the
:keyfunction, if any), is compared with the
cars of alist; if it matches, it is replaced by the corresponding
These functions perform operations on lists which represent sets of elements.
equalto item. The
memberfunction is built-in to Emacs 19; this package defines it equivalently in Emacs 18. See the following function for a Common-Lisp compatible version.
carwas the matching element. Otherwise, it returns
nil. Elements are compared by
eqlby default; you can use the
:keyarguments to modify this behavior. See section Sequences.
Note that this function's name is suffixed by `*' to avoid
member function defined in Emacs 19.
(That function uses
equal for comparisons; it is equivalent
(member* item list :test 'equal).)
analogously search for elements which satisfy a given predicate.
tif sublist is a sublist of list, i.e., if sublist is
eqlto list or to any of its
(cons item list), but only if item is not already present on the list (as determined by
member*). If a
:keyargument is specified, it is applied to item as well as to the elements of list during the search, on the reasoning that item is "about" to become part of the list.
union; rather than copying, it tries to reuse the storage of the argument lists if possible.
intersection. It tries to reuse storage of list1 rather than copying. It does not reuse the storage of list2.
set-difference, which will try to reuse list1 if possible.
set-exclusive-or, which will try to reuse list1 and list2 if possible.
An association list is a list representing a mapping from one set of values to another; any list whose elements are cons cells is an association list.
carmatches (in the sense of
:key, or by comparison with
eql) a given item. It returns the matching element, if any, otherwise
nil. It ignores elements of a-list which are not cons cells. (This corresponds to the behavior of
associn Emacs Lisp; Common Lisp's
nils but considers any other non-cons elements of a-list to be an error.)
cdrmatches item. If a-list represents a mapping, this applies the inverse of the mapping to item.
equal. It is analogous to Emacs Lisp's standard
assocfunction, which derives from the MacLisp rather than the Common Lisp tradition.
rassoc-if-not functions are defined similarly.
Two simple functions for constructing association lists are:
(cons (cons key value) alist).
(nconc (mapcar* 'cons keys values) alist).
Go to the first, previous, next, last section, table of contents.