[elpa] externals/dash 1ca9d6b 1/3: Improve -partial and -applify

[ELPA Syncer]

branch: externals/dash
commit 1ca9d6b9b27cf1e08f6b978004869e692141ab4d
Author: Basil L. Contovounesios <contovob@tcd.ie>
Commit: Basil L. Contovounesios <contovob@tcd.ie>

    Improve -partial and -applify
    
    * dash.el (-partial): Define as alias of apply-partially.
    (-applify): Mark as pure and side-effect-free.  Simplify for speed.
    * dev/examples.el (-partial, -applify): Extend tests.
    
    * README.md:
    * dash.texi: Regenerate docs.
---
 README.md       | 29 ++++++++++++++++-------------
 dash.el         | 15 ++++++---------
 dash.texi       | 34 ++++++++++++++++++++--------------
 dev/examples.el | 19 ++++++++++++++-----
 4 files changed, 56 insertions(+), 41 deletions(-)

diff --git a/README.md b/README.md
index 2b1dba6..4947b6d 100644
--- a/README.md
+++ b/README.md
@@ -367,7 +367,7 @@ Macros that modify variables holding lists.
 
 Functions that manipulate and compose other functions.
 
-* [`-partial`](#-partial-fn-rest-args) `(fn &rest args)`
+* [`-partial`](#-partial-fun-rest-args) `(fun &rest args)`
 * [`-rpartial`](#-rpartial-fn-rest-args) `(fn &rest args)`
 * [`-juxt`](#-juxt-rest-fns) `(&rest fns)`
 * [`-compose`](#-compose-rest-fns) `(&rest fns)`
@@ -2795,16 +2795,18 @@ Destructive: Set `list` to the cdr of `list`.
 
 Functions that manipulate and compose other functions.
 
-#### -partial `(fn &rest args)`
+#### -partial `(fun &rest args)`
 
-Take a function `fn` and fewer than the normal arguments to `fn`,
-and return a fn that takes a variable number of additional `args`.
-When called, the returned function calls `fn` with `args` first and
-then additional args.
+Return a function that is a partial application of `fun` to `args`.
+`args` is a list of the first `n` arguments to pass to `fun`.
+The result is a new function which does the same as `fun`, except that
+the first `n` arguments are fixed at the values with which this function
+was called.
 
 ```el
-(funcall (-partial '- 5) 3) ;; => 2
-(funcall (-partial '+ 5 2) 3) ;; => 10
+(funcall (-partial #'+ 5)) ;; => 5
+(funcall (-partial #'- 5) 3) ;; => 2
+(funcall (-partial #'+ 5 2) 3) ;; => 10
 ```
 
 #### -rpartial `(fn &rest args)`
@@ -2847,13 +2849,14 @@ the arguments (right-to-left).
 
 #### -applify `(fn)`
 
-Changes an n-arity function `fn` to a 1-arity function that
-expects a list with n items as arguments
+Return a function that applies `fn` to a single list of args.
+This changes the arity of `fn` from taking `n` distinct arguments to
+taking 1 argument which is a list of `n` arguments.
 
 ```el
-(-map (-applify '+) '((1 1 1) (1 2 3) (5 5 5))) ;; => (3 6 15)
-(-map (-applify (lambda (a b c) `(,a (,b (,c))))) '((1 1 1) (1 2 3) (5 5 5))) 
;; => ((1 (1 (1))) (1 (2 (3))) (5 (5 (5))))
-(funcall (-applify '<) '(3 6)) ;; => t
+(funcall (-applify #'+) nil) ;; => 0
+(mapcar (-applify #'+) '((1 1 1) (1 2 3) (5 5 5))) ;; => (3 6 15)
+(funcall (-applify #'<) '(3 6)) ;; => t
 ```
 
 #### -on `(operator transformer)`
diff --git a/dash.el b/dash.el
index c5fdc94..ffcf55f 100644
--- a/dash.el
+++ b/dash.el
@@ -2999,12 +2999,7 @@ structure such as plist or alist."
 
 ;;; Combinators
 
-(defun -partial (fn &rest args)
-  "Take a function FN and fewer than the normal arguments to FN,
-and return a fn that takes a variable number of additional ARGS.
-When called, the returned function calls FN with ARGS first and
-then additional args."
-  (apply 'apply-partially fn args))
+(defalias '-partial #'apply-partially)
 
 (defun -rpartial (fn &rest args)
   "Takes a function FN and fewer than the normal arguments to FN,
@@ -3031,9 +3026,11 @@ the arguments (right-to-left)."
                          args fns))))
 
 (defun -applify (fn)
-  "Changes an n-arity function FN to a 1-arity function that
-expects a list with n items as arguments"
-  (apply-partially 'apply fn))
+  "Return a function that applies FN to a single list of args.
+This changes the arity of FN from taking N distinct arguments to
+taking 1 argument which is a list of N arguments."
+  (declare (pure t) (side-effect-free t))
+  (lambda (args) (apply fn args)))
 
 (defun -on (operator transformer)
   "Return a function of two arguments that first applies
diff --git a/dash.texi b/dash.texi
index cbf8133..dcfbe0d 100644
--- a/dash.texi
+++ b/dash.texi
@@ -4201,19 +4201,24 @@ Destructive: Set @var{list} to the cdr of @var{list}.
 Functions that manipulate and compose other functions.
 
 @anchor{-partial}
-@defun -partial (fn &rest args)
-Take a function @var{fn} and fewer than the normal arguments to @var{fn},
-and return a fn that takes a variable number of additional @var{args}.
-When called, the returned function calls @var{fn} with @var{args} first and
-then additional args.
+@defun -partial (fun &rest args)
+Return a function that is a partial application of @var{fun} to @var{args}.
+@var{args} is a list of the first @var{n} arguments to pass to @var{fun}.
+The result is a new function which does the same as @var{fun}, except that
+the first @var{n} arguments are fixed at the values with which this function
+was called.
 
 @example
 @group
-(funcall (-partial '- 5) 3)
+(funcall (-partial #'+ 5))
+    @result{} 5
+@end group
+@group
+(funcall (-partial #'- 5) 3)
     @result{} 2
 @end group
 @group
-(funcall (-partial '+ 5 2) 3)
+(funcall (-partial #'+ 5 2) 3)
     @result{} 10
 @end group
 @end example
@@ -4283,20 +4288,21 @@ the arguments (right-to-left).
 
 @anchor{-applify}
 @defun -applify (fn)
-Changes an n-arity function @var{fn} to a 1-arity function that
-expects a list with n items as arguments
+Return a function that applies @var{fn} to a single list of args.
+This changes the arity of @var{fn} from taking @var{n} distinct arguments to
+taking 1 argument which is a list of @var{n} arguments.
 
 @example
 @group
-(-map (-applify '+) '((1 1 1) (1 2 3) (5 5 5)))
-    @result{} (3 6 15)
+(funcall (-applify #'+) nil)
+    @result{} 0
 @end group
 @group
-(-map (-applify (lambda (a b c) `(,a (,b (,c))))) '((1 1 1) (1 2 3) (5 5 5)))
-    @result{} ((1 (1 (1))) (1 (2 (3))) (5 (5 (5))))
+(mapcar (-applify #'+) '((1 1 1) (1 2 3) (5 5 5)))
+    @result{} (3 6 15)
 @end group
 @group
-(funcall (-applify '<) '(3 6))
+(funcall (-applify #'<) '(3 6))
     @result{} t
 @end group
 @end example
diff --git a/dev/examples.el b/dev/examples.el
index 6997d89..35acfd4 100644
--- a/dev/examples.el
+++ b/dev/examples.el
@@ -1633,8 +1633,12 @@ or readability."
   "Functions that manipulate and compose other functions."
 
   (defexamples -partial
-    (funcall (-partial '- 5) 3) => 2
-    (funcall (-partial '+ 5 2) 3) => 10)
+    (funcall (-partial #'+ 5)) => 5
+    (funcall (-partial #'- 5) 3) => 2
+    (funcall (-partial #'+ 5 2) 3) => 10
+    (funcall (-partial #'+)) => 0
+    (funcall (-partial #'+) 5) => 5
+    (apply (-partial #'+ 5) 10 '(1 2)) => 18)
 
   (unless (version< emacs-version "24")
     (defexamples -rpartial
@@ -1652,9 +1656,14 @@ or readability."
       (funcall (-compose (-compose 'not 'even?) 'square) 3) => (funcall 
(-compose 'not (-compose 'even? 'square)) 3)))
 
   (defexamples -applify
-    (-map (-applify '+) '((1 1 1) (1 2 3) (5 5 5))) => '(3 6 15)
-    (-map (-applify (lambda (a b c) `(,a (,b (,c))))) '((1 1 1) (1 2 3) (5 5 
5))) => '((1 (1 (1))) (1 (2 (3))) (5 (5 (5))))
-    (funcall (-applify '<) '(3 6)) => t)
+    (funcall (-applify #'+) ()) => 0
+    (mapcar (-applify #'+) '((1 1 1) (1 2 3) (5 5 5))) => '(3 6 15)
+    (funcall (-applify #'<) '(3 6)) => t
+    (apply (-applify #'+) '(())) => 0
+    (apply (-applify #'+) '((1 2))) => 3
+    (funcall (-applify #'+)) !!> wrong-number-of-arguments
+    (mapcar (-applify (lambda (a b) `(,a (,b)))) '((1 1) (1 2) (5 5)))
+    => '((1 (1)) (1 (2)) (5 (5))))
 
   (unless (version< emacs-version "24")
     (defexamples -on