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 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.
(car x)
. Likewise,
the functions second
, third
, ..., through
tenth
return the given element of the list x.
(cdr x)
.
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
.
(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.)
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))
.
The Emacs function last
does the same thing
except that it does not handle the optional argument n.
(append (butlast x n)
(last x n))
will return a list equal to x.
butlast
that works by destructively
modifying the cdr
of the appropriate element, rather than
making a copy of the list.
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*
.)
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.
(1 2 . 3)
correctly.
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.
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 section Sequences.
@secno=3
These functions substitute elements throughout a tree of cons
cells. (See section Sequence Functions, for the substitute
function, which works on just the top-level elements of a list.)
car
s and cdr
s
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 (eql
by default).
The :key
function is applied to the elements of the tree
but not to old.
subst
, except that it works by
destructive modification (by setcar
or setcdr
)
rather than copying.
The subst-if
, subst-if-not
, nsubst-if
, and
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 :key
function, if any), is compared with the car
s of
alist; if it matches, it is replaced by the corresponding
cdr
.
sublis
.
These functions perform operations on lists which represent sets of elements.
equal
to item. The member
function is
built-in to Emacs 19; this package defines it equivalently in Emacs 18.
See the following function for a Common-Lisp compatible version.
car
was
the matching element. Otherwise, it returns nil
. Elements
are compared by eql
by default; you can use the :test
,
:test-not
, and :key
arguments to modify this behavior.
See section Sequences.
Note that this function's name is suffixed by `*' to avoid
the incompatible member
function defined in Emacs 19.
(That function uses equal
for comparisons; it is equivalent
to (member* item list :test 'equal)
.)
The member-if
and member-if-not
functions
analogously search for elements which satisfy a given predicate.
t
if sublist is a sublist of
list, i.e., if sublist is eql
to list or to
any of its cdr
s.
(cons item list)
, but only if item
is not already present on the list (as determined by member*
).
If a :key
argument 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.
car
matches (in the sense of :test
,
:test-not
, and :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
assq
and assoc
in Emacs Lisp; Common Lisp's
assoc
ignores nil
s but considers any other non-cons
elements of a-list to be an error.)
cdr
matches
item. If a-list represents a mapping, this applies
the inverse of the mapping to item.
rassoc*
with a :test
argument of equal
. It is analogous to Emacs Lisp's
standard assoc
function, which derives from the MacLisp
rather than the Common Lisp tradition.
The assoc-if
, assoc-if-not
, rassoc-if
,
and 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.