master cbd862865ff 7/9: Remove `sort-on` (bug#69709)

[Mattias Engdegård]

branch: master
commit cbd862865ff0a08d1214ac33590e7af80d10a0ac
Author: Mattias Engdegård <mattiase@acm.org>
Commit: Mattias Engdegård <mattiase@acm.org>

    Remove `sort-on` (bug#69709)
    
    * lisp/sort.el (sort-on):
    * doc/lispref/sequences.texi (Sequence Functions):
    * etc/NEWS:
    Remove the `sort-on` function which is now completely superseded by
    the extended `sort` in features, ease of use, and performance.
---
 doc/lispref/sequences.texi | 40 ++++------------------------------------
 etc/NEWS                   |  5 -----
 lisp/sort.el               | 21 ---------------------
 3 files changed, 4 insertions(+), 62 deletions(-)

diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi
index 6322f17e77b..de83b96d748 100644
--- a/doc/lispref/sequences.texi
+++ b/doc/lispref/sequences.texi
@@ -440,6 +440,10 @@ where @var{predicate} is the @code{:lessp} argument.  When 
using this
 form, sorting is always done in-place.
 @end defun
 
+@xref{Sorting}, for more functions that perform sorting.  See
+@code{documentation} in @ref{Accessing Documentation}, for a useful
+example of @code{sort}.
+
 @cindex comparing values
 @cindex standard sorting order
 @anchor{definition of value<}
@@ -476,42 +480,6 @@ Examples:
 @end example
 @end defun
 
-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
-or vector element exactly once.
-
-@cindex decorate-sort-undecorate
-@cindex Schwartzian transform
-@defun sort-on sequence predicate accessor
-This function stably sorts @var{sequence}, which can be a list, a
-vector, a bool-vector, or a string.  It sorts by 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, or 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
-@code{documentation} in @ref{Accessing Documentation}, for a useful
-example of @code{sort}.
-
 @cindex sequence functions in seq
 @cindex seq library
 @cindex sequences, generalized
diff --git a/etc/NEWS b/etc/NEWS
index 4018df1fecb..6cefe11a2cc 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1795,11 +1795,6 @@ sorts by the return value of 'age', then by 'size', then 
by 'cost'.
 The old signature, '(sort SEQ PREDICATE)', can still be used and sorts
 its input in-place as before.
 
-** New function 'sort-on'.
-This function implements the Schwartzian transform, and is appropriate
-for sorting lists when the computation of the sort key of a list
-element can be expensive.
-
 ** New API for 'derived-mode-p' and control of the graph of major modes.
 
 *** 'derived-mode-p' now takes the list of modes as a single argument.
diff --git a/lisp/sort.el b/lisp/sort.el
index 4f0d759ef8a..2ee76b6e1e3 100644
--- a/lisp/sort.el
+++ b/lisp/sort.el
@@ -478,27 +478,6 @@ sRegexp specifying key within record: \nr")
                          ;; if there was no such register
                          (error (throw 'key nil))))))))))
 
-;;;###autoload
-(defun sort-on (sequence predicate accessor)
-  "Sort SEQUENCE by calling PREDICATE on sort keys produced by ACCESSOR.
-SEQUENCE should be the input sequence 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
-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
-expensive operation.  This is known as the \"decorate-sort-undecorate\"
-paradigm, or the Schwartzian transform."
-  (mapcar #'car
-          (sort (mapcar #'(lambda (x) (cons x (funcall accessor x))) sequence)
-                #'(lambda (x y) (funcall predicate (cdr x) (cdr y))))))
-
 
 (defvar sort-columns-subprocess t)