(lispref.info)List Elements


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

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 less than zero, then the first element is returned.

          (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 less than or equal to zero, then all of LIST is returned.
     If the length of LIST is N or less, the value is `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)


automatically generated by info2www