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

Function: nthcdr n list

This function returns the nth CDR of list. In other words, it removes 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)

Many convenience functions are provided to make it easier for you to access particular elements in a nested list. All of these can be rewritten in terms of the functions just described.

Function: caar cons-cell

Function: cadr cons-cell

Function: cdar cons-cell

Function: cddr cons-cell

Function: caaar cons-cell

Function: caadr cons-cell

Function: cadar cons-cell

Function: caddr cons-cell

Function: cdaar cons-cell

Function: cdadr cons-cell

Function: cddar cons-cell

Function: cdddr cons-cell

Function: caaaar cons-cell

Function: caaadr cons-cell

Function: caadar cons-cell

Function: caaddr cons-cell

Function: cadaar cons-cell

Function: cadadr cons-cell

Function: caddar cons-cell

Function: cadddr cons-cell

Function: cdaaar cons-cell

Function: cdaadr cons-cell

Function: cdadar cons-cell

Function: cdaddr cons-cell

Function: cddaar cons-cell

Function: cddadr cons-cell

Function: cdddar cons-cell

Function: cddddr cons-cell

Each of these functions is equivalent to one or more applications of car and/or cdr. For example,

(cadr x)

is equivalent to

(car (cdr x))

and

(cdaddr x)

is equivalent to

(cdr (car (cdr (cdr x))))

That is to say, read the a’s and d’s from right to left and apply a car or cdr for each a or d found, respectively.

Function: first list

This is equivalent to (nth 0 list), i.e. the first element of list. (Note that this is also equivalent to car.)

Function: second list

This is equivalent to (nth 1 list), i.e. the second element of list.

Function: third list

Function: fourth list

Function: fifth list

Function: sixth list

Function: seventh list

Function: eighth list

Function: ninth list

Function: tenth list

These are equivalent to (nth 2 list) through (nth 9 list) respectively, i.e. the third through tenth elements of list.