Accessing Elements of Lists

Function: 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

Function: 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

Function: 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))

Function: 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))

Macro: 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.

Function: 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.

Function: 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.

An alias for nthcdr is drop.

(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)

Function: 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.

In general, (append (take n list) (drop n list)) will return a list equal to list.

(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

Function: 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.

Function: drop-while pred list

This function skips leading list elements for which the predicate pred returns non-nil, and returns the rest.

(drop-while #'numberp '(1 2 a b 3 4))
     ⇒ (a b 3 4)

Function: take-while pred list

This function returns the leading list elements for which the predicate pred returns non-nil, and ignores the rest.

In general, (append (take-while p list) (drop-while p list)) will return a list equal to list.

(take-while #'numberp '(1 2 a b 3 4))
     ⇒ (1 2)

Function: all pred list

This function returns t if pred is true for all elements in list.

(all #'numberp '(1 2 3 4))     ⇒ t
(all #'numberp '(1 2 a b 3 4)) ⇒ nil
(all #'numberp '())            ⇒ t

Function: member-if pred list

This function returns non-nil if pred is true for at least one element in list. The returned value is the longest list suffix whose first element satisfies pred.

(member-if #'symbolp '(1 2 3 4))     ⇒ nil
(member-if #'symbolp '(1 2 a b 3 4)) ⇒ (a b 3 4)
(member-if #'symbolp '())            ⇒ nil

Function: any pred list

This function is an alias for member-if. It may be preferable in contexts which do not make use of the returned value but only whether or not it was nil.

Function: 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.

Function: 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.

Function: caar cons-cell

This is the same as (car (car cons-cell)).

Function: cadr cons-cell

This is the same as (car (cdr cons-cell)) or (nth 1 cons-cell).

Function: cdar cons-cell

This is the same as (cdr (car cons-cell)).

Function: 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.

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.