[elpa] externals/dash de67c4b 188/439: Add `-sort`

[Phillip Lord]

branch: externals/dash
commit de67c4b0a71e73fe4bbfb587f42a6c8845808f7f
Author: Magnar Sveen <address@hidden>
Commit: Magnar Sveen <address@hidden>

    Add `-sort`
    
    Fixes #34
---
 README.md       |   14 ++++++++++++++
 dash.el         |   12 ++++++++++++
 dev/examples.el |    6 ++++++
 3 files changed, 32 insertions(+), 0 deletions(-)

diff --git a/README.md b/README.md
index 98954d7..b08f657 100644
--- a/README.md
+++ b/README.md
@@ -62,6 +62,7 @@ Or you can just dump `dash.el` in your load path somewhere.
 * [-intersection](#-intersection-list-list2) `(list list2)`
 * [-distinct](#-distinct-list) `(list)`
 * [-contains?](#-contains-list-element) `(list element)`
+* [-sort](#-sort-predicate-list) `(predicate list)`
 * [-partial](#-partial-fn-rest-args) `(fn &rest args)`
 * [-rpartial](#-rpartial-fn-rest-args) `(fn &rest args)`
 * [-applify](#-applify-fn) `(fn)`
@@ -675,6 +676,19 @@ or with `-compare-fn` if that's non-nil.
 (-contains? '(1 2 3) 4) ;; => nil
 ```
 
+### -sort `(predicate list)`
+
+Sort `list`, stably, comparing elements using `predicate`.
+Returns the sorted list.  `list` is `not` modified by side effects.
+`predicate` is called with two elements of `list`, and should return non-nil
+if the first element should sort before the second.
+
+```cl
+(-sort '< '(3 1 2)) ;; => '(1 2 3)
+(-sort '> '(3 1 2)) ;; => '(3 2 1)
+(--sort (< it other) '(3 1 2)) ;; => '(1 2 3)
+```
+
 ### -partial `(fn &rest args)`
 
 Takes a function `fn` and fewer than the normal arguments to `fn`,
diff --git a/dash.el b/dash.el
index fc7dded..5994eaa 100644
--- a/dash.el
+++ b/dash.el
@@ -853,6 +853,18 @@ or with `-compare-fn' if that's non-nil."
 
 (defalias '-contains-p '-contains?)
 
+(defun -sort (predicate list)
+  "Sort LIST, stably, comparing elements using PREDICATE.
+Returns the sorted list.  LIST is NOT modified by side effects.
+PREDICATE is called with two elements of LIST, and should return non-nil
+if the first element should sort before the second."
+  (sort (copy-sequence list) predicate))
+
+(defmacro --sort (form list)
+  "Anaphoric form of `-sort'."
+  (declare (debug t))
+  `(-sort (lambda (it other) ,form) ,list))
+
 (defun -repeat (n x)
   "Return a list with X repeated N times.
 Returns nil if N is less than 1."
diff --git a/dev/examples.el b/dev/examples.el
index 0bb9710..48561ba 100644
--- a/dev/examples.el
+++ b/dev/examples.el
@@ -275,6 +275,12 @@
   (-contains? '() 1) => nil
   (-contains? '() '()) => nil)
 
+(defexamples -sort
+  (-sort '< '(3 1 2)) => '(1 2 3)
+  (-sort '> '(3 1 2)) => '(3 2 1)
+  (--sort (< it other) '(3 1 2)) => '(1 2 3)
+  (let ((l '(3 1 2))) (-sort '> l) l) => '(3 1 2))
+
 (defexamples -partial
   (funcall (-partial '- 5) 3) => 2
   (funcall (-partial '+ 5 2) 3) => 10)