Next: Building Lists, Previous: List-related Predicates, Up: 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 ofcons-cell.As a special case, if

cons-cellis`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 ofcons-cell.As a special case, if

cons-cellis`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

objectifobjectis a cons cell,`nil`

otherwise. This is in contrast to`car`

, which signals an error ifobjectis not a list.(car-safeobject) == (let ((xobject)) (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

objectifobjectis a cons cell,`nil`

otherwise. This is in contrast to`cdr`

, which signals an error ifobjectis not a list.(cdr-safeobject) == (let ((xobject)) (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 intolistname, then returns the removed element.In the simplest case,

listnameis 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,

listnamecan be a generalized variable. In that case, this macro saves intolistnameusing`setf`

. See Generalized Variables.For the

`push`

macro, which adds an element to a list, See List Variables.

— Function: **nth**` n list`

This function returns the

nth element oflist. Elements are numbered starting with zero, so the car oflistis element number zero. If the length oflistisnor 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 Sequence Functions.

— Function: **nthcdr**` n list`

This function returns the

nth cdr oflist. In other words, it skips past the firstnlinks oflistand returns what follows.If

nis zero,`nthcdr`

returns all oflist. If the length oflistisnor 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)

— Function: **last**` list &optional n`

This function returns the last link of

list. The`car`

of this link is the list's last element. Iflistis null,`nil`

is returned. Ifnis non-`nil`

, thenth-to-last link is returned instead, or the whole oflistifnis bigger thanlist'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

listis 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 Sequence Functions.

In addition to the above, 24 additional compositions of `car`

and
`cdr`

are defined as `c`

`xxx``r`

and `c`

`xxxx``r`

,
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.