[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
Re: lispref/variables.texi
From:
Luc Teirlinck
Subject:
Re: lispref/variables.texi
Date:
2005年6月24日 19:56:47 -0500 (CDT)
Kim Storm wrote:
To "remove" the order, you can specify a non-nil, non-numeric value
for ORDER -- in that case, the element's order in the hash table is
set to nil (which effitively means "no" ordering).
I actually did not know that. Then a few further changes to
variables.texi are needed, as well as some changes to the
add-to-ordered-list docstring. The current docs suggest that only
numbers or nil values for ORDER are allowed. On an unrelated note,
the first lines of the docstrings of both add-to-ordered-list and
add-to-list needlessly exceed the maximum allowed 67 characters. I
believe that the shortened versions in the patch below are actually
not only shorter, but better readable as well.
Below are a proposed new patch to subr.el and a slightly revised
version of my patch to variables.texi.
===File ~/subr.el-diff======================================
*** subr.el 22 Jun 2005 18:21:04 -0500 1.468
--- subr.el 24 Jun 2005 19:22:52 -0500
***************
*** 937,943 ****
(set hook hook-value))))))
(defun add-to-list (list-var element &optional append)
! "Add to the value of LIST-VAR the element ELEMENT if it isn't there yet.
The test for presence of ELEMENT is done with `equal'.
If ELEMENT is added, it is added at the beginning of the list,
unless the optional argument APPEND is non-nil, in which case
--- 937,943 ----
(set hook hook-value))))))
(defun add-to-list (list-var element &optional append)
! "Add ELEMENT to the value of LIST-VAR if it isn't there yet.
The test for presence of ELEMENT is done with `equal'.
If ELEMENT is added, it is added at the beginning of the list,
unless the optional argument APPEND is non-nil, in which case
***************
*** 959,973 ****
(defun add-to-ordered-list (list-var element &optional order)
! "Add to the value of LIST-VAR the element ELEMENT if it isn't there yet.
The test for presence of ELEMENT is done with `eq'.
The resulting list is reordered so that the elements are in the
order given by each element's numeric list order. Elements
without a numeric list order are placed at the end of the list.
! If the third optional argument ORDER is non-nil, set the
! element's list order to the given value.
The list order for each element is stored in LIST-VAR's
`list-order' property.
--- 959,976 ----
(defun add-to-ordered-list (list-var element &optional order)
! "Add ELEMENT to the value of LIST-VAR if it isn't there yet.
The test for presence of ELEMENT is done with `eq'.
The resulting list is reordered so that the elements are in the
order given by each element's numeric list order. Elements
without a numeric list order are placed at the end of the list.
! If the third optional argument ORDER is a number (integer or
! float), set the element's list order to the given value. If
! ORDER is nil or omitted, do not change the numeric order of
! ELEMENT. If ORDER has any other value, remove the numeric order
! of ELEMENT if it has one.
The list order for each element is stored in LIST-VAR's
`list-order' property.
============================================================
===File ~/variables.texi-diff===============================
*** variables.texi 20 Jun 2005 17:10:57 -0500 1.66
--- variables.texi 24 Jun 2005 19:17:50 -0500
***************
*** 909,926 ****
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.
! 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 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
@code{list-order} property.
@end defun
--- 909,933 ----
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
***************
*** 945,955 ****
(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)
foo ;; @address@hidden was changed.}
! @result{} (a b c d)
@end example
@node Variable Scoping
--- 952,962 ----
(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)
@end example
@node Variable Scoping
============================================================