compat-30: Add sort-on

4 files changed, 51 insertions, 0 deletions

diff --git a/NEWS.org b/NEWS.org
index 4fbb0bc..f1c380f 100644
--- a/NEWS.org
+++ b/NEWS.org
@@ -4,6 +4,7 @@
 
 * Development
 
+- compat-30: Add =sort-on=.
 - compat-30: Add extended =copy-tree= with support for copying records with
   non-nil optional second argument.
 - compat-30: New macro =static-if=.
diff --git a/compat-30.el b/compat-30.el
index cd9ad76..a831c4e 100644
--- a/compat-30.el
+++ b/compat-30.el
@@ -27,6 +27,27 @@
 ;; TODO Update to 30.1 as soon as the Emacs emacs-30 branch version bumped
 (compat-version "30.0.50")
 
+;;;; Defined in sort.el
+
+(compat-defun sort-on (sequence predicate accessor) ;; <compat-tests:sort-on>
+  "Sort SEQUENCE by calling PREDICATE on sort keys produced by ACCESSOR.
+SEQUENCE should be the input list 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.
+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))))))
+
 ;;;; Defined in buffer.c
 
 (compat-defun find-buffer (variable value) ;; <compat-tests:find-buffer>
diff --git a/compat-tests.el b/compat-tests.el
index 8340d5f..71bcc08 100644
--- a/compat-tests.el
+++ b/compat-tests.el
@@ -1753,6 +1753,15 @@
   (should-equal '(1 2 3 4) (flatten-tree '((1) nil 2 ((3 4)))))
   (should-equal '(1 2 3 4) (flatten-tree '(((1 nil)) 2 (((3 nil nil) 4))))))
 
+(ert-deftest compat-sort-on ()
+  ;; TODO enable if CI emacs 30 supports sort-on
+  (static-if (< emacs-major-version 30)
+    (progn
+      (should-equal '(3 2 1) (sort-on '(2 1 3) #'> #'identity))
+      (should-equal '(1 2 3) (sort-on [2 1 3] #'< #'identity))
+      (should-equal '((1 z) (2 y) (3 x)) (sort-on (list '(2 y) '(1 z) '(3 x)) #'< #'car))
+      (should-equal '((x 3) (y 2) (z 1)) (sort-on (list '(y 2) '(z 1) '(x 3)) #'> #'cadr)))))
+
 (ert-deftest compat-sort ()
   (should-equal (list 1 2 3) (sort (list 1 2 3) #'<))
   (should-equal (list 1 2 3) (sort (list 1 3 2) #'<))
diff --git a/compat.texi b/compat.texi
index f80a622..066e0b1 100644
--- a/compat.texi
+++ b/compat.texi
@@ -3348,6 +3348,26 @@ older than 30.1.  Note that due to upstream changes, it might happen
 that there will be the need for changes, so use these functions with
 care.
 
+@c copied from lispref/sequences.texi
+@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
+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.
+@end defun
+
 @defun get-truename-buffer filename
 Return the buffer with @code{file-truename} equal to @var{filename} (a string).
 If there is no such live buffer, return nil.