[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A list represents a sequence of zero or more elements (which may be any Lisp objects). The important difference between lists and vectors is that two or more lists can share part of their structure; in addition, you can insert or delete elements in a list without copying the whole list.
5.1 Lists and Cons Cells | How lists are made out of cons cells. | |
5.2 Lists as Linked Pairs of Boxes | Graphical notation to explain lists. | |
5.3 Predicates on Lists | Is this object a list? Comparing two lists. | |
5.4 Accessing Elements of Lists | Extracting the pieces of a list. | |
5.5 Building Cons Cells and Lists | Creating list structure. | |
5.6 Modifying Existing List Structure | Storing new pieces into an existing list. | |
5.7 Using Lists as Sets | A list can represent a finite mathematical set. | |
5.8 Association Lists | A list can represent a finite relation or mapping. |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Lists in Lisp are not a primitive data type; they are built up from cons cells. A cons cell is a data object that represents an ordered pair. That is, it has two slots, and each slot holds, or refers to, some Lisp object. One slot is known as the CAR, and the other is known as the CDR. (These names are traditional; see 2.3.6 Cons Cell and List Types.) CDR is pronounced "could-er."
We say that "the CAR of this cons cell is" whatever object its CAR slot currently holds, and likewise for the CDR.
A list is a series of cons cells "chained together," so that each
cell refers to the next one. There is one cons cell for each element of
the list. By convention, the CARs of the cons cells hold the
elements of the list, and the CDRs are used to chain the list: the
CDR slot of each cons cell refers to the following cons cell. The
CDR of the last cons cell is nil
. This asymmetry between
the CAR and the CDR is entirely a matter of convention; at the
level of cons cells, the CAR and CDR slots have the same
characteristics.
Because most cons cells are used as part of lists, the phrase list structure has come to mean any structure made out of cons cells.
The symbol nil
is considered a list as well as a symbol; it is
the list with no elements. For convenience, the symbol nil
is
considered to have nil
as its CDR (and also as its
CAR).
The CDR of any nonempty list l is a list containing all the elements of l except the first.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A cons cell can be illustrated as a pair of boxes. The first box
represents the CAR and the second box represents the CDR.
Here is an illustration of the two-element list, (tulip lily)
,
made from two cons cells:
--------------- --------------- | car | cdr | | car | cdr | | tulip | o---------->| lily | nil | | | | | | | --------------- --------------- |
Each pair of boxes represents a cons cell. Each box "refers to",
"points to" or "holds" a Lisp object. (These terms are
synonymous.) The first box, which describes the CAR of the first
cons cell, contains the symbol tulip
. The arrow from the
CDR box of the first cons cell to the second cons cell indicates
that the CDR of the first cons cell is the second cons cell.
The same list can be illustrated in a different sort of box notation like this:
--- --- --- --- | | |--> | | |--> nil --- --- --- --- | | | | --> tulip --> lily |
Here is a more complex illustration, showing the three-element list,
((pine needles) oak maple)
, the first element of which is a
two-element list:
--- --- --- --- --- --- | | |--> | | |--> | | |--> nil --- --- --- --- --- --- | | | | | | | --> oak --> maple | | --- --- --- --- --> | | |--> | | |--> nil --- --- --- --- | | | | --> pine --> needles |
The same list represented in the first box notation looks like this:
-------------- -------------- -------------- | car | cdr | | car | cdr | | car | cdr | | o | o------->| oak | o------->| maple | nil | | | | | | | | | | | -- | --------- -------------- -------------- | | | -------------- ---------------- | | car | cdr | | car | cdr | ------>| pine | o------->| needles | nil | | | | | | | -------------- ---------------- |
See section 2.3.6 Cons Cell and List Types, for the read and print syntax of cons cells and lists, and for more "box and arrow" illustrations of lists.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following predicates test whether a Lisp object is an atom, is a
cons cell or is a list, or whether it is the distinguished object
nil
. (Many of these predicates can be defined in terms of the
others, but they are used so often that it is worth having all of them.)
t
if object is a cons cell, nil
otherwise. nil
is not a cons cell, although it is a list.
t
if object is an atom, nil
otherwise. All objects except cons cells are atoms. The symbol
nil
is an atom and is also a list; it is the only Lisp object
that is both.
(atom object) == (not (consp object)) |
t
if object is a cons cell or
nil
. Otherwise, it returns nil
.
(listp '(1)) => t (listp '()) => t |
listp
: it returns t
if
object is not a list. Otherwise, it returns nil
.
(listp object) == (not (nlistp object)) |
t
if object is nil
, and
returns nil
otherwise. This function is identical to not
,
but as a matter of clarity we use null
when object is
considered a list and not
when it is considered a truth value
(see not
in 10.3 Constructs for Combining Conditions).
(null '(1)) => nil (null '()) => t |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
As a special case, if cons-cell is nil
, then car
is defined to return nil
; therefore, any list is a valid argument
for car
. An error is signaled if the argument is not a cons cell
or nil
.
(car '(a b c)) => a (car '()) => nil |
As a special case, if cons-cell is nil
, then cdr
is defined to return nil
; therefore, any list is a valid argument
for cdr
. An error is signaled if the argument is not a cons cell
or nil
.
(cdr '(a b c)) => (b c) (cdr '()) => nil |
nil
otherwise. This is in contrast
to car
, which signals an error if object is not a list.
(car-safe object) == (let ((x object)) (if (consp x) (car x) nil)) |
nil
otherwise.
This is in contrast to cdr
, which signals an error if
object is not a list.
(cdr-safe object) == (let ((x object)) (if (consp x) (cdr x) nil)) |
It operates on the list which is stored in the symbol listname. It removes this element from the list by setting listname to the CDR of its old value--but it also returns the CAR of that list, which is the element being removed.
x => (a b c) (pop x) => a x => (b c) |
nil
.
If n is negative, nth
returns the first element of
list.
(nth 2 '(1 2 3 4)) => 3 (nth 10 '(1 2 3 4)) => nil (nth -3 '(1 2 3 4)) => 1 (nth n x) == (car (nthcdr n x)) |
The function elt
is similar, but applies to any kind of sequence.
For historical reasons, it takes its arguments in the opposite order.
See section 6.1 Sequences.
If n is zero or negative, nthcdr
returns all of
list. If the length of list is n or less,
nthcdr
returns nil
.
(nthcdr 1 '(1 2 3 4)) => (2 3 4) (nthcdr 10 '(1 2 3 4)) => nil (nthcdr -3 '(1 2 3 4)) => (1 2 3 4) |
car
of this link is the list's last element. If list is
null, nil
is returned. If n is non-nil the
n-th-to-last link is returned instead, or the whole list if
n is bigger than list's length.
If list is not really a list, safe-length
returns 0. If
list is circular, it returns a finite value which is at least the
number of distinct elements.
The most common way to compute the length of a list, when you are not
worried that it may be circular, is with length
. See section 6.1 Sequences.
(car (car cons-cell))
.
(car (cdr cons-cell))
or (nth 1 cons-cell)
.
(cdr (car cons-cell))
.
(cdr (cdr cons-cell))
or (nthcdr 2 cons-cell)
.
(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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Many functions build lists, as lists reside at the very heart of Lisp.
cons
is the fundamental list-building function; however, it is
interesting to note that list
is used more times in the source
code for Emacs than cons
.
(cons 1 '(2)) => (1 2) (cons 1 '()) => (1) (cons 1 2) => (1 . 2) |
cons
is often used to add a single element to the front of a
list. This is called consing the element onto the list.
(1)
For example:
(setq list (cons newelt list)) |
Note that there is no conflict between the variable named list
used in this example and the function named list
described below;
any symbol can serve both purposes.
(setq listname (cons newelt listname))
.
It is new in Emacs 21.
(setq l '(a b)) => (a b) (push 'c l) => (c a b) l => (c a b) |
nil
-terminated. If no objects
are given, the empty list is returned.
(list 1 2 3 4 5) => (1 2 3 4 5) (list 1 2 '(3 4 5) 'foo) => (1 2 (3 4 5) foo) (list) => nil |
make-list
with
make-string
(see section 4.3 Creating Strings).
(make-list 3 'pigs) => (pigs pigs pigs) (make-list 0 'pigs) => nil (setq l (make-list 3 '(a b)) => ((a b) (a b) (a b)) (eq (car l) (cadr l)) => t |
nconc
in 5.6.3 Functions that Rearrange Lists, for a way to join
lists with no copying.)
More generally, the final argument to append
may be any Lisp
object. The final argument is not copied or converted; it becomes the
CDR of the last cons cell in the new list. If the final argument
is itself a list, then its elements become in effect elements of the
result list. If the final element is not a list, the result is a
"dotted list" since its final CDR is not nil
as required
in a true list.
The append
function also allows integers as arguments. It
converts them to strings of digits, making up the decimal print
representation of the integer, and then uses the strings instead of the
original integers. Don't use this feature; we plan to eliminate
it. If you already use this feature, change your programs now! The
proper way to convert an integer to a decimal number in this way is with
format
(see section 4.7 Formatting Strings) or number-to-string
(see section 4.6 Conversion of Characters and Strings).
Here is an example of using append
:
(setq trees '(pine oak)) => (pine oak) (setq more-trees (append '(maple birch) trees)) => (maple birch pine oak) trees => (pine oak) more-trees => (maple birch pine oak) (eq trees (cdr (cdr more-trees))) => t |
You can see how append
works by looking at a box diagram. The
variable trees
is set to the list (pine oak)
and then the
variable more-trees
is set to the list (maple birch pine
oak)
. However, the variable trees
continues to refer to the
original list:
more-trees trees | | | --- --- --- --- -> --- --- --- --- --> | | |--> | | |--> | | |--> | | |--> nil --- --- --- --- --- --- --- --- | | | | | | | | --> maple -->birch --> pine --> oak |
An empty sequence contributes nothing to the value returned by
append
. As a consequence of this, a final nil
argument
forces a copy of the previous argument:
trees => (pine oak) (setq wood (append trees nil)) => (pine oak) wood => (pine oak) (eq wood trees) => nil |
This once was the usual way to copy a list, before the function
copy-sequence
was invented. See section 6. Sequences, Arrays, and Vectors.
Here we show the use of vectors and strings as arguments to append
:
(append [a b] "cd" nil) => (a b 99 100) |
With the help of apply
(see section 12.5 Calling Functions), we can append
all the lists in a list of lists:
(apply 'append '((a b c) nil (x y z) nil)) => (a b c x y z) |
If no sequences are given, nil
is returned:
(append) => nil |
Here are some examples where the final argument is not a list:
(append '(x y) 'z) => (x y . z) (append '(x y) [z]) => (x y . [z]) |
The second example shows that when the final argument is a sequence but not a list, the sequence's elements do not become elements of the resulting list. Instead, the sequence becomes the final CDR, like any other non-list final argument.
(setq x '(1 2 3 4)) => (1 2 3 4) (reverse x) => (4 3 2 1) x => (1 2 3 4) |
eq
to object. The letter `q' in remq
says that it uses eq
to compare object against the elements
of list
.
(setq sample-list '(a b c a b c)) => (a b c a b c) (remq 'a sample-list) => (b c b c) sample-list => (a b c a b c) |
delq
offers a way to perform this operation
destructively. See 5.7 Using Lists as Sets.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
You can modify the CAR and CDR contents of a cons cell with the
primitives setcar
and setcdr
. We call these "destructive"
operations because they change existing list structure.
Common Lisp note: Common Lisp uses functionsrplaca
andrplacd
to alter list structure; they change structure the same way assetcar
andsetcdr
, but the Common Lisp functions return the cons cell whilesetcar
andsetcdr
return the new CAR or CDR.
5.6.1 Altering List Elements with setcar | Replacing an element in a list. | |
5.6.2 Altering the CDR of a List | Replacing part of the list backbone. This can be used to remove or add elements. | |
5.6.3 Functions that Rearrange Lists | Reordering the elements in a list; combining lists. |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
setcar
Changing the CAR of a cons cell is done with setcar
. When
used on a list, setcar
replaces one element of a list with a
different element.
(setq x '(1 2)) => (1 2) (setcar x 4) => 4 x => (4 2) |
When a cons cell is part of the shared structure of several lists, storing a new CAR into the cons changes one element of each of these lists. Here is an example:
;; Create two lists that are partly shared. (setq x1 '(a b c)) => (a b c) (setq x2 (cons 'z (cdr x1))) => (z b c) ;; Replace the CAR of a shared link. (setcar (cdr x1) 'foo) => foo x1 ; Both lists are changed. => (a foo c) x2 => (z foo c) ;; Replace the CAR of a link that is not shared. (setcar x1 'baz) => baz x1 ; Only one list is changed. => (baz foo c) x2 => (z foo c) |
Here is a graphical depiction of the shared structure of the two lists
in the variables x1
and x2
, showing why replacing b
changes them both:
--- --- --- --- --- --- x1---> | | |----> | | |--> | | |--> nil --- --- --- --- --- --- | --> | | | | | | --> a | --> b --> c | --- --- | x2--> | | |-- --- --- | | --> z |
Here is an alternative form of box diagram, showing the same relationship:
x1: -------------- -------------- -------------- | car | cdr | | car | cdr | | car | cdr | | a | o------->| b | o------->| c | nil | | | | -->| | | | | | -------------- | -------------- -------------- | x2: | -------------- | | car | cdr | | | z | o---- | | | -------------- |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The lowest-level primitive for modifying a CDR is setcdr
:
Here is an example of replacing the CDR of a list with a different list. All but the first element of the list are removed in favor of a different sequence of elements. The first element is unchanged, because it resides in the CAR of the list, and is not reached via the CDR.
(setq x '(1 2 3)) => (1 2 3) (setcdr x '(4)) => (4) x => (1 4) |
You can delete elements from the middle of a list by altering the
CDRs of the cons cells in the list. For example, here we delete
the second element, b
, from the list (a b c)
, by changing
the CDR of the first cons cell:
(setq x1 '(a b c)) => (a b c) (setcdr x1 (cdr (cdr x1))) => (c) x1 => (a c) |
Here is the result in box notation:
-------------------- | | -------------- | -------------- | -------------- | car | cdr | | | car | cdr | -->| car | cdr | | a | o----- | b | o-------->| c | nil | | | | | | | | | | -------------- -------------- -------------- |
The second cons cell, which previously held the element b
, still
exists and its CAR is still b
, but it no longer forms part
of this list.
It is equally easy to insert a new element by changing CDRs:
(setq x1 '(a b c)) => (a b c) (setcdr x1 (cons 'd (cdr x1))) => (d b c) x1 => (a d b c) |
Here is this result in box notation:
-------------- ------------- ------------- | car | cdr | | car | cdr | | car | cdr | | a | o | -->| b | o------->| c | nil | | | | | | | | | | | | --------- | -- | ------------- ------------- | | ----- -------- | | | --------------- | | | car | cdr | | -->| d | o------ | | | --------------- |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Here are some functions that rearrange lists "destructively" by modifying the CDRs of their component cons cells. We call these functions "destructive" because they chew up the original lists passed to them as arguments, relinking their cons cells to form a new list that is the returned value.
See delq
, in 5.7 Using Lists as Sets, for another function
that modifies cons cells.
append
(see section 5.5 Building Cons Cells and Lists), the lists are
not copied. Instead, the last CDR of each of the
lists is changed to refer to the following list. The last of the
lists is not altered. For example:
(setq x '(1 2 3)) => (1 2 3) (nconc x '(4 5)) => (1 2 3 4 5) x => (1 2 3 4 5) |
Since the last argument of nconc
is not itself modified, it is
reasonable to use a constant list, such as '(4 5)
, as in the
above example. For the same reason, the last argument need not be a
list:
(setq x '(1 2 3)) => (1 2 3) (nconc x 'z) => (1 2 3 . z) x => (1 2 3 . z) |
However, the other arguments (all but the last) must be lists.
A common pitfall is to use a quoted constant list as a non-last
argument to nconc
. If you do this, your program will change
each time you run it! Here is what happens:
(defun add-foo (x) ; We want this function to add
(nconc '(foo) x)) ; |
reverse
, nreverse
alters its argument by reversing
the CDRs in the cons cells forming the list. The cons cell that
used to be the last one in list becomes the first cons cell of the
value.
For example:
(setq x '(a b c)) => (a b c) x => (a b c) (nreverse x) => (c b a) ;; The cons cell that was first is now last. x => (a) |
To avoid confusion, we usually store the result of nreverse
back in the same variable which held the original list:
(setq x (nreverse x)) |
Here is the nreverse
of our favorite example, (a b c)
,
presented graphically:
Original list head: Reversed list: ------------- ------------- ------------ | car | cdr | | car | cdr | | car | cdr | | a | nil |<-- | b | o |<-- | c | o | | | | | | | | | | | | | | ------------- | --------- | - | -------- | - | | | | ------------- ------------ |
The argument predicate must be a function that accepts two
arguments. It is called with two elements of list. To get an
increasing order sort, the predicate should return t
if the
first element is "less than" the second, or nil
if not.
The comparison function predicate must give reliable results for
any given pair of arguments, at least within a single call to
sort
. It must be antisymmetric; that is, if a is
less than b, b must not be less than a. It must be
transitive---that is, if a is less than b, and b
is less than c, then a must be less than c. If you
use a comparison function which does not meet these requirements, the
result of sort
is unpredictable.
The destructive aspect of sort
is that it rearranges the cons
cells forming list by changing CDRs. A nondestructive sort
function would create new cons cells to store the elements in their
sorted order. If you wish to make a sorted copy without destroying the
original, copy it first with copy-sequence
and then sort.
Sorting does not change the CARs of the cons cells in list;
the cons cell that originally contained the element a
in
list still has a
in its CAR after sorting, but it now
appears in a different position in the list due to the change of
CDRs. For example:
(setq nums '(1 3 2 6 5 4 0)) => (1 3 2 6 5 4 0) (sort nums '<) => (0 1 2 3 4 5 6) nums => (1 2 3 4 5 6) |
Warning: Note that the list in nums
no longer contains
0; this is the same cons cell that it was before, but it is no longer
the first one in the list. Don't assume a variable that formerly held
the argument now holds the entire sorted list! Instead, save the result
of sort
and use that. Most often we store the result back into
the variable that held the original list:
(setq nums (sort nums '<)) |
See section 32.15 Sorting Text, for more functions that perform sorting.
See documentation
in 24.2 Access to Documentation Strings, for a
useful example of sort
.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A list can represent an unordered mathematical set--simply consider a
value an element of a set if it appears in the list, and ignore the
order of the list. To form the union of two sets, use append
(as
long as you don't mind having duplicate elements). Other useful
functions for sets include memq
and delq
, and their
equal
versions, member
and delete
.
Common Lisp note: Common Lisp has functionsunion
(which avoids duplicate elements) andintersection
for set operations, but GNU Emacs Lisp does not have them. You can write them in Lisp if you wish.
memq
returns a list starting with the
first occurrence of object. Otherwise, it returns nil
.
The letter `q' in memq
says that it uses eq
to
compare object against the elements of the list. For example:
(memq 'b '(a b c b a)) => (b c b a) (memq '(2) '((1) (2))) ; |
member
, except that it ignores
differences in letter-case and text representation: upper-case and
lower-case letters are treated as equal, and unibyte strings are
converted to multibyte prior to comparison.
eq
to
object from list. The letter `q' in delq
says
that it uses eq
to compare object against the elements of
the list, like memq
and remq
.
When delq
deletes elements from the front of the list, it does so
simply by advancing down the list and returning a sublist that starts
after those elements:
(delq 'a '(a b c)) == (cdr '(a b c)) |
When an element to be deleted appears in the middle of the list, removing it involves changing the CDRs (see section 5.6.2 Altering the CDR of a List).
(setq sample-list '(a b c (4))) => (a b c (4)) (delq 'a sample-list) => (b c (4)) sample-list => (a b c (4)) (delq 'c sample-list) => (a b (4)) sample-list => (a b (4)) |
Note that (delq 'c sample-list)
modifies sample-list
to
splice out the third element, but (delq 'a sample-list)
does not
splice anything--it just returns a shorter list. Don't assume that a
variable which formerly held the argument list now has fewer
elements, or that it still holds the original list! Instead, save the
result of delq
and use that. Most often we store the result back
into the variable that held the original list:
(setq flowers (delq 'rose flowers)) |
In the following example, the (4)
that delq
attempts to match
and the (4)
in the sample-list
are not eq
:
(delq '(4) sample-list) => (a c (4)) |
The following two functions are like memq
and delq
but use
equal
rather than eq
to compare elements. See section 2.7 Equality Predicates.
member
tests to see whether object is a member
of list, comparing members with object using equal
.
If object is a member, member
returns a list starting with
its first occurrence in list. Otherwise, it returns nil
.
Compare this with memq
:
(member '(2) '((1) (2))) ; |
sequence
is a list, this function destructively removes all
elements equal
to object from sequence. For lists,
delete
is to delq
as member
is to memq
: it
uses equal
to compare elements with object, like
member
; when it finds an element that matches, it removes the
element just as delq
would.
If sequence
is a vector or string, delete
returns a copy
of sequence
with all elements equal
to object
removed.
For example:
(delete '(2) '((2) (1) (2))) => ((1)) (delete '(2) [(2) (1) (2)]) => [(1)] |
delete
. If
returns a copy of sequence
, a list, vector, or string, with
elements equal
to object
removed. For example:
(remove '(2) '((2) (1) (2))) => ((1)) (remove '(2) [(2) (1) (2)]) => [(1)] |
Common Lisp note: The functionsmember
,delete
andremove
in GNU Emacs Lisp are derived from Maclisp, not Common Lisp. The Common Lisp versions do not useequal
to compare elements.
See also the function add-to-list
, in 11.8 How to Alter a Variable Value,
for another way to add an element to a list stored in a variable.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
An association list, or alist for short, records a mapping from keys to values. It is a list of cons cells called associations: the CAR of each cons cell is the key, and the CDR is the associated value.(2)
Here is an example of an alist. The key pine
is associated with
the value cones
; the key oak
is associated with
acorns
; and the key maple
is associated with seeds
.
((pine . cones) (oak . acorns) (maple . seeds)) |
The associated values in an alist may be any Lisp objects; so may the
keys. For example, in the following alist, the symbol a
is
associated with the number 1
, and the string "b"
is
associated with the list (2 3)
, which is the CDR of
the alist element:
((a . 1) ("b" 2 3)) |
Sometimes it is better to design an alist to store the associated value in the CAR of the CDR of the element. Here is an example of such an alist:
((rose red) (lily white) (buttercup yellow)) |
Here we regard red
as the value associated with rose
. One
advantage of this kind of alist is that you can store other related
information--even a list of other items--in the CDR of the
CDR. One disadvantage is that you cannot use rassq
(see
below) to find the element containing a given value. When neither of
these considerations is important, the choice is a matter of taste, as
long as you are consistent about it for any given alist.
Note that the same alist shown above could be regarded as having the
associated value in the CDR of the element; the value associated
with rose
would be the list (red)
.
Association lists are often used to record information that you might otherwise keep on a stack, since new associations may be added easily to the front of the list. When searching an association list for an association with a given key, the first one found is returned, if there is more than one.
In Emacs Lisp, it is not an error if an element of an association list is not a cons cell. The alist search functions simply ignore such elements. Many other versions of Lisp signal errors in such cases.
Note that property lists are similar to association lists in several respects. A property list behaves like an association list in which each key can occur only once. See section 8.4 Property Lists, for a comparison of property lists and association lists.
equal
(see section 2.7 Equality Predicates). It returns nil
if no
association in alist has a CAR equal
to key.
For example:
(setq trees '((pine . cones) (oak . acorns) (maple . seeds))) => ((pine . cones) (oak . acorns) (maple . seeds)) (assoc 'oak trees) => (oak . acorns) (cdr (assoc 'oak trees)) => acorns (assoc 'birch trees) => nil |
Here is another example, in which the keys and values are not symbols:
(setq needles-per-cluster '((2 "Austrian Pine" "Red Pine") (3 "Pitch Pine") (5 "White Pine"))) (cdr (assoc 3 needles-per-cluster)) => ("Pitch Pine") (cdr (assoc 2 needles-per-cluster)) => ("Austrian Pine" "Red Pine") |
The functions assoc-ignore-representation
and
assoc-ignore-case
are much like assoc
except using
compare-strings
to do the comparison. See section 4.5 Comparison of Characters and Strings.
nil
if no association in alist has
a CDR equal
to value.
rassoc
is like assoc
except that it compares the CDR of
each alist association instead of the CAR. You can think of
this as "reverse assoc
", finding the key for a given value.
assoc
in that it returns the first
association for key in alist, but it makes the comparison
using eq
instead of equal
. assq
returns nil
if no association in alist has a CAR eq
to key.
This function is used more often than assoc
, since eq
is
faster than equal
and most alists use symbols as keys.
See section 2.7 Equality Predicates.
(setq trees '((pine . cones) (oak . acorns) (maple . seeds))) => ((pine . cones) (oak . acorns) (maple . seeds)) (assq 'pine trees) => (pine . cones) |
On the other hand, assq
is not usually useful in alists where the
keys may not be symbols:
(setq leaves '(("simple leaves" . oak) ("compound leaves" . horsechestnut))) (assq "simple leaves" leaves) => nil (assoc "simple leaves" leaves) => ("simple leaves" . oak) |
nil
if no association in alist has
a CDR eq
to value.
rassq
is like assq
except that it compares the CDR of
each alist association instead of the CAR. You can think of
this as "reverse assq
", finding the key for a given value.
For example:
(setq trees '((pine . cones) (oak . acorns) (maple . seeds))) (rassq 'acorns trees) => (oak . acorns) (rassq 'spores trees) => nil |
Note that rassq
cannot search for a value stored in the CAR
of the CDR of an element:
(setq colors '((rose red) (lily white) (buttercup yellow))) (rassq 'white colors) => nil |
In this case, the CDR of the association (lily white)
is not
the symbol white
, but rather the list (white)
. This
becomes clearer if the association is written in dotted pair notation:
(lily white) == (lily . (white)) |
string-match
with an alist that contains
regular expressions (see section 34.3 Regular Expression Searching). If test is omitted
or nil
, equal
is used for comparison.
If an alist element matches key by this criterion,
then assoc-default
returns a value based on this element.
If the element is a cons, then the value is the element's CDR.
Otherwise, the return value is default.
If no alist element matches key, assoc-default
returns
nil
.
(setq needles-per-cluster '((2 . ("Austrian Pine" "Red Pine")) (3 . ("Pitch Pine")) (5 . ("White Pine")))) => ((2 "Austrian Pine" "Red Pine") (3 "Pitch Pine") (5 "White Pine")) (setq copy (copy-alist needles-per-cluster)) => ((2 "Austrian Pine" "Red Pine") (3 "Pitch Pine") (5 "White Pine")) (eq needles-per-cluster copy) => nil (equal needles-per-cluster copy) => t (eq (car needles-per-cluster) (car copy)) => nil (cdr (car (cdr needles-per-cluster))) => ("Pitch Pine") (eq (cdr (car (cdr needles-per-cluster))) (cdr (car (cdr copy)))) => t |
This example shows how copy-alist
makes it possible to change
the associations of one copy without affecting the other:
(setcdr (assq 3 copy) '("Martian Vacuum Pine")) (cdr (assq 3 needles-per-cluster)) => ("Pitch Pine") |
eq
to key. It returns alist, modified
in this way. Note that it modifies the original list structure
of alist.
(assq-delete-all 'foo '((foo 1) (bar 2) (foo 3) (lose 4))) => ((bar 2) (lose 4)) |
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |