Commit 39872724 authored by Richard M. Stallman's avatar Richard M. Stallman
Browse files

(List Variables): New node.

Material moved from other nodes.
parent 17f6554c
......@@ -20,6 +20,7 @@ the whole list.
* 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 @@ used in this example and the function named @code{list} described below;
any symbol can serve both purposes.
@end defun
@defmac push newelt listname
This macro provides an alternative way to write
@code{(setq @var{listname} (cons @var{newelt} @var{listname}))}.
@example
(setq l '(a b))
@result{} (a b)
(push 'c l)
@result{} (c a b)
l
@result{} (c a b)
@end example
@end 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 @@ Some examples:
@end example
@end defun
@node List Variables
@section Modifying List Variables
These functions, and one macro, provide convenient ways
to modify a list which is stored in a variable.
@defmac push newelt listname
This macro provides an alternative way to write
@code{(setq @var{listname} (cons @var{newelt} @var{listname}))}.
@example
(setq l '(a b))
@result{} (a b)
(push 'c l)
@result{} (c a b)
l
@result{} (c a b)
@end example
@end defmac
Two functions modify lists that are the values of variables.
@defun 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
@var{symbol}, but if the optional argument @var{append} is
non-@code{nil}, 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.
@end defun
Here's a scenario showing how to use @code{add-to-list}:
@example
(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 ;; @r{@code{foo} was changed.}
@result{} (c a b)
@end example
An equivalent expression for @code{(add-to-list '@var{var}
@var{value})} is this:
@example
(or (member @var{value} @var{var})
(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}.
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.
@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 a hash table 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 'e) ;; @r{Add @code{e}}.
@result{} (a c b e d)
foo ;; @r{@code{foo} was changed.}
@result{} (a c b e d)
@end example
@node Modifying Lists
@section Modifying Existing List Structure
@cindex destructive list operations
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment