[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to emacs/lispref/lists.texi,v
From: |
Richard M. Stallman |
Subject: |
[Emacs-diffs] Changes to emacs/lispref/lists.texi,v |
Date: |
Mon, 24 Jul 2006 17:54:38 +0000 |
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
- [Emacs-diffs] Changes to emacs/lispref/lists.texi,v, Eli Zaretskii, 2006/07/08
- [Emacs-diffs] Changes to emacs/lispref/lists.texi,v, Karl Berry, 2006/07/16
- [Emacs-diffs] Changes to emacs/lispref/lists.texi,v, Richard M. Stallman, 2006/07/17
- [Emacs-diffs] Changes to emacs/lispref/lists.texi,v,
Richard M. Stallman <=
- [Emacs-diffs] Changes to emacs/lispref/lists.texi,v, Nick Roberts, 2006/07/31