[Emacs-diffs] Changes to emacs/lispref/variables.texi

[Kim F . Storm]

Index: emacs/lispref/variables.texi
diff -c emacs/lispref/variables.texi:1.65 emacs/lispref/variables.texi:1.66
*** emacs/lispref/variables.texi:1.65   Sat Jun 18 13:58:02 2005
--- emacs/lispref/variables.texi        Mon Jun 20 21:44:59 2005
***************
*** 903,908 ****
--- 903,957 ----
      (setq @var{var} (cons @var{value} @var{var})))
  @end example
  
+ @defun add-to-ordered-list symbol element &optional order
+ This function sets the variable @var{symbol} by inserting
+ @var{element} into the old value, which must be a list, at the
+ position specified by @var{order}.  If @var{element} is already a
+ member of the list, its position in the list is adjusted according
+ to @var{order}.  Membership is tested using @code{eq}.
+ The valued returned is the resulting list, whether updated or not.
+ 
+ The @var{order} is a number, and the elements on list are sorted in
+ increasing numerical order.  Elements without a numeric list order are
+ placed at the end of @var{symbol}.
+ 
+ The argument @var{symbol} is not implicitly quoted;
+ @code{add-to-ordered-list} is an ordinary function, like @code{set}
+ and unlike @code{setq}.  Quote the argument yourself if that is what
+ you want.
+ 
+ The ordering information is stored in an alist on @var{symbol}'s
+ @code{list-order} property.
+ @end defun
+ 
+ Here's a scenario showing how to use @code{add-to-ordered-list}:
+ 
+ @example
+ (setq foo '())
+      @result{} nil
+ 
+ (add-to-ordered-list 'foo 'a 1)     ;; @r{Add @code{a}.}
+      @result{} (a)
+ 
+ (add-to-ordered-list 'foo 'c 3)     ;; @r{Add @code{c}.}
+      @result{} (a c)
+ 
+ (add-to-ordered-list 'foo 'b 2)     ;; @r{Add @code{b}.}
+      @result{} (a b c)
+ 
+ (add-to-ordered-list 'foo 'b 4)     ;; @r{Move @code{b}.}
+      @result{} (a c b)
+ 
+ (add-to-ordered-list 'foo 'd)       ;; @r{Append @code{d}.}
+      @result{} (a c b d)
+ 
+ (add-to-ordered-list 'foo 'b 2)     ;; @r{Move @code{b}.}
+      @result{} (a b c d)
+ 
+ foo                       ;; @address@hidden was changed.}
+      @result{} (a b c d)
+ @end example
+ 
  @node Variable Scoping
  @section Scoping Rules for Variable Bindings