(Setting Variables): Any type of element can be

given order in add-to-ordered-list.  Compare elements with eq.

1 files changed, 49 insertions, 0 deletions

diff --git a/lispref/variables.texi b/lispref/variables.texi
index 8ee941892c9..31e42b59c79 100644
--- a/lispref/variables.texi
+++ b/lispref/variables.texi
@@ -903,6 +903,55 @@ foo                       ;; @r{@code{foo} was changed.}
     (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                       ;; @r{@code{foo} was changed.}
+     @result{} (a b c d)
+@end example
+
 @node Variable Scoping
 @section Scoping Rules for Variable Bindings