car
cons-cell ¶This function returns the value referred to by the first slot of the cons cell cons-cell. In other words, it returns the CAR of cons-cell.
As a special case, if cons-cell is nil
, this function
returns nil
. Therefore, any list is a valid argument. An
error is signaled if the argument is not a cons cell or nil
.
(car '(a b c)) ⇒ a
(car '()) ⇒ nil
cdr
cons-cell ¶This function returns the value referred to by the second slot of the cons cell cons-cell. In other words, it returns the CDR of cons-cell.
As a special case, if cons-cell is nil
, this function
returns nil
; therefore, any list is a valid argument. An error
is signaled if the argument is not a cons cell or nil
.
(cdr '(a b c)) ⇒ (b c)
(cdr '()) ⇒ nil
car-safe
object ¶This function lets you take the CAR of a cons cell while avoiding
errors for other data types. It returns the CAR of object if
object is a cons cell, 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))
cdr-safe
object ¶This function lets you take the CDR of a cons cell while
avoiding errors for other data types. It returns the CDR of
object if object is a cons cell, 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))
pop
listname ¶This macro provides a convenient way to examine the CAR of a list, and take it off the list, all at once. It operates on the list stored in listname. It removes the first element from the list, saves the CDR into listname, then returns the removed element.
In the simplest case, listname is an unquoted symbol naming a
list; in that case, this macro is equivalent to (prog1 (car listname) (setq listname (cdr listname)))
.
x ⇒ (a b c) (pop x) ⇒ a x ⇒ (b c)
More generally, listname can be a generalized variable. In that
case, this macro saves into listname using setf
.
See Generalized Variables.
For the push
macro, which adds an element to a list,
See Modifying List Variables.
nth
n list ¶This function returns the nth element of list. Elements
are numbered starting with zero, so the CAR of list is
element number zero. If the length of list is n or less,
the value is nil
.
(nth 2 '(1 2 3 4)) ⇒ 3
(nth 10 '(1 2 3 4)) ⇒ nil (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 Sequences.
nthcdr
n list ¶This function returns the nth CDR of list. In other words, it skips past the first n links of list and returns what follows.
If n is zero, 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 0 '(1 2 3 4)) ⇒ (1 2 3 4)
take
n list ¶This function returns the n first elements of list. Essentially,
it returns the part of list that nthcdr
skips.
take
returns list if shorter than n elements;
it returns nil
if n is zero or negative.
(take 3 '(a b c d)) ⇒ (a b c)
(take 10 '(a b c d)) ⇒ (a b c d)
(take 0 '(a b c d)) ⇒ nil
ntake
n list ¶This is a version of take
that works by destructively modifying
the list structure of the argument. That makes it faster, but the
original value of list may be lost.
ntake
returns list unmodified if shorter than n
elements; it returns nil
if n is zero or negative.
Otherwise, it returns list truncated to its first n
elements.
This means that it is usually a good idea to use the return value and not just rely on the truncation effect unless n is known to be positive.
last
list &optional n ¶This function returns the last link of list. The car
of
this link is the list’s last element. If list is null,
nil
is returned. If n is non-nil
, the
nth-to-last link is returned instead, or the whole of list
if n is bigger than list’s length.
safe-length
list ¶This function returns the length of list, with no risk of either an error or an infinite loop. It generally returns the number of distinct cons cells in the list. However, for circular lists, the value is just an upper bound; it is often too large.
If list is not nil
or a cons cell, safe-length
returns 0.
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 Sequences.
caar
cons-cell ¶This is the same as (car (car cons-cell))
.
cadr
cons-cell ¶This is the same as (car (cdr cons-cell))
or (nth 1 cons-cell)
.
cdar
cons-cell ¶This is the same as (cdr (car cons-cell))
.
cddr
cons-cell ¶This is the same as (cdr (cdr cons-cell))
or (nthcdr 2 cons-cell)
.
In addition to the above, 24 additional compositions of car
and
cdr
are defined as cxxxr
and cxxxxr
,
where each x
is either a
or d
. cadr
,
caddr
, and cadddr
pick out the second, third or fourth
elements of a list, respectively. cl-lib provides the same
under the names cl-second
, cl-third
, and
cl-fourth
. See List Functions in Common Lisp
Extensions.
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.
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.