GNU Info

(elisp)List Elements

---

Next: Building Lists Prev: List-related Predicates Up: Lists

---

Enter node , (file) or (file)node

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.  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 referred to by the second slot 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))

 - Macro: pop listname
     This macro is a way of examining the CAR of a list, and taking it
     off the list, all at once.  It is new in Emacs 21.

     It operates on the list which is stored in the symbol LISTNAME.
     It removes this element from the list by setting LISTNAME to the
     CDR of its old value--but it also returns the CAR of that list,
     which is the element being removed.

          x
               => (a b c)
          (pop x)
               => a
          x
               => (b c)

 - 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.  Note: Sequence Functions.

 - 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: 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 N-th-to-last link is returned
     instead, or the whole 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.

     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'.  Note: Sequence
Functions.

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

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