comparison lispref/variables.texi @ 63798:fe7324a36ce5

(Setting Variables): Correct and clarify description of `add-to-ordered-list'.
author Luc Teirlinck <teirllm@auburn.edu>
date Mon, 27 Jun 2005 21:33:00 +0000
parents 443baf51aba7
children 6b1ddf9e6581
comparison
equal deleted inserted replaced
63797:7f964f8f5c85 63798:fe7324a36ce5
907 This function sets the variable @var{symbol} by inserting 907 This function sets the variable @var{symbol} by inserting
908 @var{element} into the old value, which must be a list, at the 908 @var{element} into the old value, which must be a list, at the
909 position specified by @var{order}. If @var{element} is already a 909 position specified by @var{order}. If @var{element} is already a
910 member of the list, its position in the list is adjusted according 910 member of the list, its position in the list is adjusted according
911 to @var{order}. Membership is tested using @code{eq}. 911 to @var{order}. Membership is tested using @code{eq}.
912 The valued returned is the resulting list, whether updated or not. 912 This function returns the resulting list, whether updated or not.
913 913
914 The @var{order} is a number, and the elements on list are sorted in 914 The @var{order} is typically a number (integer or float), and the
915 increasing numerical order. Elements without a numeric list order are 915 elements of the list are sorted in non-decreasing numerical order.
916 placed at the end of @var{symbol}. 916
917 @var{order} may also be omitted or @code{nil}. Then the numeric order
918 of @var{element} stays unchanged if it already has one; otherwise,
919 @var{element} has no numeric order. Elements without a numeric list
920 order are placed at the end of the list, in no particular order.
921
922 Any other value for @var{order} removes the numeric order of @var{element}
923 if it already has one; otherwise, it is equivalent to @code{nil}.
917 924
918 The argument @var{symbol} is not implicitly quoted; 925 The argument @var{symbol} is not implicitly quoted;
919 @code{add-to-ordered-list} is an ordinary function, like @code{set} 926 @code{add-to-ordered-list} is an ordinary function, like @code{set}
920 and unlike @code{setq}. Quote the argument yourself if that is what 927 and unlike @code{setq}. Quote the argument yourself if that is what
921 you want. 928 you want.
922 929
923 The ordering information is stored in an alist on @var{symbol}'s 930 The ordering information is stored in a hash table on @var{symbol}'s
924 @code{list-order} property. 931 @code{list-order} property.
925 @end defun 932 @end defun
926 933
927 Here's a scenario showing how to use @code{add-to-ordered-list}: 934 Here's a scenario showing how to use @code{add-to-ordered-list}:
928 935
943 @result{} (a c b) 950 @result{} (a c b)
944 951
945 (add-to-ordered-list 'foo 'd) ;; @r{Append @code{d}.} 952 (add-to-ordered-list 'foo 'd) ;; @r{Append @code{d}.}
946 @result{} (a c b d) 953 @result{} (a c b d)
947 954
948 (add-to-ordered-list 'foo 'b 2) ;; @r{Move @code{b}.} 955 (add-to-ordered-list 'foo 'e) ;; @r{Add @code{e}}.
949 @result{} (a b c d) 956 @result{} (a c b e d)
950 957
951 foo ;; @r{@code{foo} was changed.} 958 foo ;; @r{@code{foo} was changed.}
952 @result{} (a b c d) 959 @result{} (a c b e d)
953 @end example 960 @end example
954 961
955 @node Variable Scoping 962 @node Variable Scoping
956 @section Scoping Rules for Variable Bindings 963 @section Scoping Rules for Variable Bindings
957 964