Accessing Elements of Lists

Function: car cons-cell

This function returns the value pointed to by the first pointer of the cons cell cons-cell. Expressed another way, this function returns the CAR of cons-cell.

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

Function: cdr cons-cell

This function returns the value pointed to by the second pointer of the cons cell cons-cell. Expressed another way, this function returns the CDR of cons-cell.

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

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

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.

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

Function: safe-length list

This function returns the length of list, with no risk of either an error or an infinite loop.

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

Go to the first, previous, next, last section, table of contents.