Info Catalog elisp: Building Lists elisp: Lists elisp: Modifying Lists

elisp: List Variables

 
 5.5 Modifying List Variables
 ============================
 
 These functions, and one macro, provide convenient ways to modify a list
 which is stored in a variable.
 
  -- Macro: push element listname
      This macro creates a new list whose CAR is ELEMENT and whose CDR is
      the list specified by LISTNAME, and saves that list in LISTNAME.
      In the simplest case, LISTNAME is an unquoted symbol naming a list,
      and this macro is equivalent to
      ‘(setq LISTNAME (cons ELEMENT LISTNAME))’.
 
           (setq l '(a b))
                ⇒ (a b)
           (push 'c l)
                ⇒ (c a b)
           l
                ⇒ (c a b)
 
      More generally, ‘listname’ can be a generalized variable.  In that
      case, this macro does the equivalent of
      ‘(setf LISTNAME (cons ELEMENT LISTNAME))’.  Generalized
      Variables.
 
      For the ‘pop’ macro, which removes the first element from a list,
      List Elements.
 
    Two functions modify lists that are the values of variables.
 
  -- Function: add-to-list symbol element &optional append compare-fn
      This function sets the variable SYMBOL by consing ELEMENT onto the
      old value, if ELEMENT is not already a member of that value.  It
      returns the resulting list, whether updated or not.  The value of
      SYMBOL had better be a list already before the call.  ‘add-to-list’
      uses COMPARE-FN to compare ELEMENT against existing list members;
      if COMPARE-FN is ‘nil’, it uses ‘equal’.
 
      Normally, if ELEMENT is added, it is added to the front of SYMBOL,
      but if the optional argument APPEND is non-‘nil’, it is added at
      the end.
 
      The argument SYMBOL is not implicitly quoted; ‘add-to-list’ is an
      ordinary function, like ‘set’ and unlike ‘setq’.  Quote the
      argument yourself if that is what you want.
 
    Here’s a scenario showing how to use ‘add-to-list’:
 
      (setq foo '(a b))
           ⇒ (a b)
 
      (add-to-list 'foo 'c)     ;; Add ‘c’.
           ⇒ (c a b)
 
      (add-to-list 'foo 'b)     ;; No effect.
           ⇒ (c a b)
 
      foo                       ;; ‘foo’ was changed.
           ⇒ (c a b)
 
    An equivalent expression for ‘(add-to-list 'VAR VALUE)’ is this:
 
      (or (member VALUE VAR)
          (setq VAR (cons VALUE VAR)))
 
  -- Function: add-to-ordered-list symbol element &optional order
      This function sets the variable SYMBOL by inserting ELEMENT into
      the old value, which must be a list, at the position specified by
      ORDER.  If ELEMENT is already a member of the list, its position in
      the list is adjusted according to ORDER.  Membership is tested
      using ‘eq’.  This function returns the resulting list, whether
      updated or not.
 
      The ORDER is typically a number (integer or float), and the
      elements of the list are sorted in non-decreasing numerical order.
 
      ORDER may also be omitted or ‘nil’.  Then the numeric order of
      ELEMENT stays unchanged if it already has one; otherwise, ELEMENT
      has no numeric order.  Elements without a numeric list order are
      placed at the end of the list, in no particular order.
 
      Any other value for ORDER removes the numeric order of ELEMENT if
      it already has one; otherwise, it is equivalent to ‘nil’.
 
      The argument SYMBOL is not implicitly quoted; ‘add-to-ordered-list’
      is an ordinary function, like ‘set’ and unlike ‘setq’.  Quote the
      argument yourself if necessary.
 
      The ordering information is stored in a hash table on SYMBOL’s
      ‘list-order’ property.
 
    Here’s a scenario showing how to use ‘add-to-ordered-list’:
 
      (setq foo '())
           ⇒ nil
 
      (add-to-ordered-list 'foo 'a 1)     ;; Add ‘a’.
           ⇒ (a)
 
      (add-to-ordered-list 'foo 'c 3)     ;; Add ‘c’.
           ⇒ (a c)
 
      (add-to-ordered-list 'foo 'b 2)     ;; Add ‘b’.
           ⇒ (a b c)
 
      (add-to-ordered-list 'foo 'b 4)     ;; Move ‘b’.
           ⇒ (a c b)
 
      (add-to-ordered-list 'foo 'd)       ;; Append ‘d’.
           ⇒ (a c b d)
 
      (add-to-ordered-list 'foo 'e)       ;; Add ‘e’.
           ⇒ (a c b e d)
 
      foo                       ;; ‘foo’ was changed.
           ⇒ (a c b e d)
 

Info Catalog elisp: Building Lists elisp: Lists elisp: Modifying Lists