GNU Emacs Lisp Reference Manual

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