Mercurial > emacs
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 |