From 27607f0c1cafa41218b4cc0538280051a60bd1ee Mon Sep 17 00:00:00 2001 From: Luc Teirlinck Date: Mon, 27 Jun 2005 21:33:00 +0000 Subject: [PATCH] (Setting Variables): Correct and clarify description of `add-to-ordered-list'. --- lispref/variables.texi | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/lispref/variables.texi b/lispref/variables.texi index 31e42b59c79..d58fc8e7540 100644 --- a/lispref/variables.texi +++ b/lispref/variables.texi @@ -909,18 +909,25 @@ This function sets the variable @var{symbol} by inserting 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. +This function returns 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 @var{order} is typically a number (integer or float), and the +elements of the list are sorted in non-decreasing numerical order. + +@var{order} may also be omitted or @code{nil}. Then the numeric order +of @var{element} stays unchanged if it already has one; otherwise, +@var{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 @var{order} removes the numeric order of @var{element} +if it already has one; otherwise, it is equivalent to @code{nil}. 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 +The ordering information is stored in a hash table on @var{symbol}'s @code{list-order} property. @end defun @@ -945,11 +952,11 @@ Here's a scenario showing how to use @code{add-to-ordered-list}: (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) +(add-to-ordered-list 'foo 'e) ;; @r{Add @code{e}}. + @result{} (a c b e d) foo ;; @r{@code{foo} was changed.} - @result{} (a b c d) + @result{} (a c b e d) @end example @node Variable Scoping -- 2.39.2