procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update manual about sort

Browse source 
* doc/lispref/sequences.texi (Sequence Functions):
Remove inaccurate and over-specific claims about how `sort` works for
lists: there is no guarantee that it doesn't modify the `car` fields
of the input list (which is precisely what it does at this time).

(cherry picked from commit c753a95923)
This commit is contained in:
Mattias Engdegård 2023-04-10 10:25:11 +02:00
parent c62afb10cf
commit 954e2d96a9
1 changed files with 25 additions and 27 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

52
doc/lispref/sequences.texi
View file

@ -376,45 +376,43 @@ is less than @var{c}, then @var{a} must be less than @var{c}. If you
use a comparison function which does not meet these requirements, the
result of @code{sort} is unpredictable.
The destructive aspect of @code{sort} for lists is that it rearranges the
cons cells forming @var{sequence} by changing @sc{cdr}s. A nondestructive
sort function would create new cons cells to store the elements in their
sorted order. If you wish to make a sorted copy without destroying the
original, copy it first with @code{copy-sequence} and then sort.
Sorting does not change the @sc{car}s of the cons cells in @var{sequence};
the cons cell that originally contained the element @code{a} in
@var{sequence} still has @code{a} in its @sc{car} after sorting, but it now
appears in a different position in the list due to the change of
@sc{cdr}s. For example:
The destructive aspect of @code{sort} for lists is that it reuses the
cons cells forming @var{sequence} by changing their contents, possibly
rearranging them in a different order. This means that the value of
the input list is undefined after sorting; only the list returned by
@code{sort} has a well-defined value. Example:
@example
@group
(setq nums (list 1 3 2 6 5 4 0))
@result{} (1 3 2 6 5 4 0)
@end group
@group
(setq nums (list 2 1 4 3 0))
(sort nums #'<)
@result{} (0 1 2 3 4 5 6)
@end group
@group
nums
@result{} (1 2 3 4 5 6)
@result{} (0 1 2 3 4)
; nums is unpredictable at this point
@end group
@end example
@noindent
@strong{Warning}: Note that the list in @code{nums} no longer contains
0; this is the same cons cell that it was before, but it is no longer
the first one in the list. Don't assume a variable that formerly held
the argument now holds the entire sorted list! Instead, save the result
of @code{sort} and use that. Most often we store the result back into
the variable that held the original list:
Most often we store the result back into the variable that held the
original list:
@example
(setq nums (sort nums #'<))
@end example
If you wish to make a sorted copy without destroying the original,
copy it first and then sort:
@example
@group
(setq nums (list 2 1 4 3 0))
(sort (copy-sequence nums) #'<)
@result{} (0 1 2 3 4)
@end group
@group
nums
@result{} (2 1 4 3 0)
@end group
@end example
For the better understanding of what stable sort is, consider the following
vector example. After sorting, all items whose @code{car} is 8 are grouped
at the beginning of @code{vector}, but their relative order is preserved.