From: Eli Zaretskii <eliz@gnu.org>
Date: Fri, 2 Feb 2024 15:39:23 +0000 (+0200)
Subject: ; Fix last change
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=58c9f259fafd811a6434f27c8d43bd4741d46a4e;p=emacs.git

; Fix last change

* lisp/sort.el (sort-on): Doc fix.

* doc/lispref/sequences.texi (Sequence Functions): Fix description
of 'sort-on'.

(cherry picked from commit f9a15b8a1559999b8dd9895a5f5bb922c4e6730f)
---

diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi
index 896dac35c8e..9407b5f6342 100644
--- a/doc/lispref/sequences.texi
+++ b/doc/lispref/sequences.texi
@@ -436,35 +436,35 @@ but their relative order is also preserved:
 @end example
 @end defun
 
-Sometimes, computation of sort keys of list elements is expensive, and
-therefore it is important to perform it the minimum number of times.
-By contrast, computing the sort keys of elements inside the
-@var{predicate} function passed to @code{sort} will generally perform
-this computation each time @var{predicate} is called with some
+Sometimes, computation of sort keys of list or vector elements is
+expensive, and therefore it is important to perform it the minimum
+number of times.  By contrast, computing the sort keys of elements
+inside the @var{predicate} function passed to @code{sort} will generally
+perform this computation each time @var{predicate} is called with some
 element.  If you can separate the computation of the sort key of an
 element into a function of its own, you can use the following sorting
 function, which guarantees that the key will be computed for each list
-element exactly once.
+or vector element exactly once.
 
 @cindex decorate-sort-undecorate
 @cindex Schwartzian transform
 @defun sort-on sequence predicate accessor
-This function stably sorts the list @var{sequence}, comparing the sort
-keys of the elements using @var{predicate}.  The comparison function
-@var{predicate} accepts two arguments, the sort keys to compare, and
-should return non-@code{nil} if the element corresponding to the first
-key should sort before the element corresponding to the second key.
-The function computes a sort key of each element by calling the
-@var{accessor} function on that element; it does so exactly once for
+This function stably sorts the list or vector @var{sequence}, comparing
+the sort keys of the elements using @var{predicate}.  The comparison
+function @var{predicate} accepts two arguments, the sort keys to
+compare, and should return non-@code{nil} if the element corresponding
+to the first key should sort before the element corresponding to the
+second key.  The function computes a sort key of each element by calling
+the @var{accessor} function on that element; it does so exactly once for
 each element of @var{sequence}.  The @var{accessor} function is called
 with a single argument, an element of @var{sequence}.
 
-This function implements what is known as
-@dfn{decorate-sort-undecorate} paradigm, of the Schwartzian transform.
-It basically trades CPU for memory, creating a temporary list with the
-computed sport keys, then mapping @code{car} over the result of
-sorting that temporary list.  Unlike with @code{sort}, the return list
-is a copy; the original list is left intact.
+This function implements what is known as @dfn{decorate-sort-undecorate}
+paradigm, of the Schwartzian transform.  It basically trades CPU for
+memory, creating a temporary list with the computed sort keys, then
+mapping @code{car} over the result of sorting that temporary list.
+Unlike with @code{sort}, the return value is always a new list; the
+original @var{sequence} is left intact.
 @end defun
 
 @xref{Sorting}, for more functions that perform sorting.  See
diff --git a/lisp/sort.el b/lisp/sort.el
index 97b40a2aef4..7047a714661 100644
--- a/lisp/sort.el
+++ b/lisp/sort.el
@@ -481,7 +481,7 @@ sRegexp specifying key within record: \nr")
 ;;;###autoload
 (defun sort-on (sequence predicate accessor)
   "Sort SEQUENCE by calling PREDICATE on sort keys produced by ACCESSOR.
-SEQUENCE should be the input list to sort.
+SEQUENCE should be the input list or vector to sort.
 Elements of SEQUENCE are sorted by keys which are obtained by
 calling ACCESSOR on each element.  ACCESSOR should be a function of
 one argument, an element of SEQUENCE, and should return the key
@@ -489,6 +489,7 @@ value to be compared by PREDICATE for sorting the element.
 PREDICATE is the function for comparing keys; it is called with two
 arguments, the keys to compare, and should return non-nil if the
 first key should sort before the second key.
+The return value is always a new list.
 This function has the performance advantage of evaluating
 ACCESSOR only once for each element in the input SEQUENCE, and is
 therefore appropriate when computing the key by ACCESSOR is an