branch: externals/dash
commit 1ca9d6b9b27cf1e08f6b978004869e692141ab4d
Author: Basil L. Contovounesios <conto...@tcd.ie>
Commit: Basil L. Contovounesios <conto...@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
