[Emacs-diffs] Changes to emacs/lispref/lists.texi,v

[Richard M. Stallman]

CVSROOT:        /cvsroot/emacs
Module name:    emacs
Changes by:     Richard M. Stallman <rms>       06/07/24 17:54:38

Index: lists.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/lispref/lists.texi,v
retrieving revision 1.61
retrieving revision 1.62
diff -u -b -r1.61 -r1.62
--- lists.texi  18 Jul 2006 00:02:50 -0000      1.61
+++ lists.texi  24 Jul 2006 17:54:38 -0000      1.62
@@ -20,6 +20,7 @@
 * List-related Predicates::        Is this object a list?  Comparing two lists.
 * List Elements::       Extracting the pieces of a list.
 * Building Lists::      Creating list structure.
+* List Variables::      Modifying lists stored in variables.
 * Modifying Lists::     Storing new pieces into an existing list.
 * Sets And Lists::      A list can represent a finite mathematical set.
 * Association Lists::   A list can represent a finite relation or mapping.
@@ -431,20 +432,6 @@
 any symbol can serve both purposes.
 @end defun
 
address@hidden push newelt listname
-This macro provides an alternative way to write
address@hidden(setq @var{listname} (cons @var{newelt} @var{listname}))}.
-
address@hidden
-(setq l '(a b))
-     @result{} (a b)
-(push 'c l)
-     @result{} (c a b)
-l
-     @result{} (c a b)
address@hidden example
address@hidden defmac
-
 @defun list &rest objects
 This function creates a list with @var{objects} as its elements.  The
 resulting list is always @code{nil}-terminated.  If no @var{objects}
@@ -704,6 +691,124 @@
 @end example
 @end defun
 
address@hidden List Variables
address@hidden Modifying List Variables
+
+  These functions, and one macro, provide convenient ways
+to modify a list which is stored in a variable.
+
address@hidden push newelt listname
+This macro provides an alternative way to write
address@hidden(setq @var{listname} (cons @var{newelt} @var{listname}))}.
+
address@hidden
+(setq l '(a b))
+     @result{} (a b)
+(push 'c l)
+     @result{} (c a b)
+l
+     @result{} (c a b)
address@hidden example
address@hidden defmac
+
+  Two functions modify lists that are the values of variables.
+
address@hidden add-to-list symbol element &optional append
+This function sets the variable @var{symbol} by consing @var{element}
+onto the old value, if @var{element} is not already a member of that
+value.  It returns the resulting list, whether updated or not.  The
+value of @var{symbol} had better be a list already before the call.
+Membership is tested using @code{equal}.
+
+Normally, if @var{element} is added, it is added to the front of
address@hidden, but if the optional argument @var{append} is
address@hidden, it is added at the end.
+
+The argument @var{symbol} is not implicitly quoted; @code{add-to-list}
+is an ordinary function, like @code{set} and unlike @code{setq}.  Quote
+the argument yourself if that is what you want.
address@hidden defun
+
+Here's a scenario showing how to use @code{add-to-list}:
+
address@hidden
+(setq foo '(a b))
+     @result{} (a b)
+
+(add-to-list 'foo 'c)     ;; @r{Add @code{c}.}
+     @result{} (c a b)
+
+(add-to-list 'foo 'b)     ;; @r{No effect.}
+     @result{} (c a b)
+
+foo                       ;; @address@hidden was changed.}
+     @result{} (c a b)
address@hidden example
+
+  An equivalent expression for @code{(add-to-list '@var{var}
address@hidden)} is this:
+
address@hidden
+(or (member @var{value} @var{var})
+    (setq @var{var} (cons @var{value} @var{var})))
address@hidden example
+
address@hidden add-to-ordered-list symbol element &optional order
+This function sets the variable @var{symbol} by inserting
address@hidden 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}.
+This function returns the resulting list, whether updated or not.
+
+The @var{order} is typically a number (integer or float), and the
+elements of the list are sorted in non-decreasing numerical order.
+
address@hidden may also be omitted or @code{nil}.  Then the numeric order
+of @var{element} stays unchanged if it already has one; otherwise,
address@hidden 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;
address@hidden 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 a hash table on @var{symbol}'s
address@hidden property.
address@hidden defun
+
+Here's a scenario showing how to use @code{add-to-ordered-list}:
+
address@hidden
+(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 'e)       ;; @r{Add @code{e}}.
+     @result{} (a c b e d)
+
+foo                       ;; @address@hidden was changed.}
+     @result{} (a c b e d)
address@hidden example
+
 @node Modifying Lists
 @section Modifying Existing List Structure
 @cindex destructive list operations