Info Catalog elisp: List-related Predicates elisp: Lists elisp: Building Lists

elisp: List Elements

 
 5.3 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.  In other words, it returns the CAR of
      CONS-CELL.
 
      As a special case, if CONS-CELL is ‘nil’, this function returns
      ‘nil’.  Therefore, any list is a valid argument.  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.  In other words, it returns the CDR of
      CONS-CELL.
 
      As a special case, if CONS-CELL is ‘nil’, this function returns
      ‘nil’; therefore, any list is a valid argument.  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 provides a convenient way to examine the CAR of a list,
      and take it off the list, all at once.  It operates on the list
      stored in LISTNAME.  It removes the first element from the list,
      saves the CDR into LISTNAME, then returns the removed element.
 
      In the simplest case, LISTNAME is an unquoted symbol naming a list;
      in that case, this macro is equivalent to
      ‘(prog1 (car listname) (setq listname (cdr listname)))’.
 
           x
                ⇒ (a b c)
           (pop x)
                ⇒ a
           x
                ⇒ (b c)
 
      More generally, LISTNAME can be a generalized variable.  In that
      case, this macro saves into LISTNAME using ‘setf’.  
      Generalized Variables.
 
      For the ‘push’ macro, which adds an element to a list, List
      Variables.
 
  -- 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’.
 
           (nth 2 '(1 2 3 4))
                ⇒ 3
           (nth 10 '(1 2 3 4))
                ⇒ nil
 
           (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.  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, ‘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 0 '(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 Nth-to-last link is returned
      instead, or the whole of 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.  It generally returns the number of
      distinct cons cells in the list.  However, for circular lists, the
      value is just an upper bound; it is often too large.
 
      If LIST is not ‘nil’ or a cons cell, ‘safe-length’ returns 0.
 
    The most common way to compute the length of a list, when you are not
 worried that it may be circular, is with ‘length’.  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.
 

Info Catalog elisp: List-related Predicates elisp: Lists elisp: Building Lists