mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2026-01-07 04:10:27 -08:00
Code Issues Projects Releases Wiki Activity

(Setting Variables): add-to-list and add-to-ordered-list moved to List

Browse source 
Variables node.
This commit is contained in:
Richard M. Stallman 2006-07-24 17:59:15 +00:00
parent 5e6f234c03
commit e1eed9a446
1 changed files with 0 additions and 99 deletions
Download patch file Download diff file Expand all files Collapse all files

99
lispref/variables.texi
View file

@ -858,105 +858,6 @@ always affects the most local existing binding.
@end quotation
@end defun
One other function for setting a variable is designed to add
an element to a list if it is not already present in the list.
@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 Variable Scoping
@section Scoping Rules for Variable Bindings