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 ;; @[EMAIL PROTECTED] was changed.}
+ @result{} (a b c d)
+ @end example
+
@node Variable Scoping
@section Scoping Rules for Variable Bindings
_______________________________________________
Emacs-diffs mailing list
[email protected]
http://lists.gnu.org/mailman/listinfo/emacs-diffs
