From dc61f4641779616122692e34a32ba2a158ee034c Mon Sep 17 00:00:00 2001 From: "Basil L. Contovounesios" Date: Mon, 11 Oct 2021 12:49:49 +0100 Subject: [PATCH] Fix overly wide docstrings * dash.el (-map-when, -map-first, -map-last, -only-some?) (-update-at, -split-with, -separate) (dash--partition-all-in-steps-reversed, -partition-all-in-steps) (-partition-in-steps, --zip-with, -union, -intersection, -prodfn): Refill and reword docstrings to fit in 80 columns. (-concat): Eta-reduce, defining as an alias of append. * dev/examples.el (-partition-all-in-steps): Add a jagged test case. * README.md: * dash.texi: Regenerate docs. Fixes #389. --- README.md | 106 +++++++++++++++++++++++++++++++-------------- dash.el | 113 ++++++++++++++++++++++++++++++++---------------- dash.texi | 104 +++++++++++++++++++++++++++++++------------- dev/examples.el | 4 ++ 4 files changed, 227 insertions(+), 100 deletions(-) diff --git a/README.md b/README.md index 08126c3..076bd51 100644 --- a/README.md +++ b/README.md @@ -165,7 +165,7 @@ Functions returning a sublist of the original list. Functions returning a modified copy of the input list. * [`-keep`](#-keep-fn-list) `(fn list)` -* [`-concat`](#-concat-rest-lists) `(&rest lists)` +* [`-concat`](#-concat-rest-sequences) `(&rest sequences)` * [`-flatten`](#-flatten-l) `(l)` * [`-flatten-n`](#-flatten-n-num-list) `(num list)` * [`-replace`](#-replace-old-new-list) `(old new list)` @@ -406,9 +406,9 @@ This function's anaphoric counterpart is `--map`. #### -map-when `(pred rep list)` -Return a new list where the elements in `list` that do not match the `pred` function -are unchanged, and where the elements in `list` that do match the `pred` function are mapped -through the `rep` function. +Use `pred` to conditionally apply `rep` to each item in `list`. +Return a copy of `list` where the items for which `pred` returns nil +are unchanged, and the rest are mapped through the `rep` function. Alias: `-replace-where` @@ -422,7 +422,9 @@ See also: [`-update-at`](#-update-at-n-func-list) #### -map-first `(pred rep list)` -Replace first item in `list` satisfying `pred` with result of `rep` called on this item. +Use `pred` to determine the first item in `list` to call `rep` on. +Return a copy of `list` where the first item for which `pred` returns +non-nil is replaced with the result of calling `rep` on that item. See also: [`-map-when`](#-map-when-pred-rep-list), [`-replace-first`](#-replace-first-old-new-list) @@ -434,7 +436,9 @@ See also: [`-map-when`](#-map-when-pred-rep-list), [`-replace-first`](#-replace- #### -map-last `(pred rep list)` -Replace last item in `list` satisfying `pred` with result of `rep` called on this item. +Use `pred` to determine the last item in `list` to call `rep` on. +Return a copy of `list` where the last item for which `pred` returns +non-nil is replaced with the result of calling `rep` on that item. See also: [`-map-when`](#-map-when-pred-rep-list), [`-replace-last`](#-replace-last-old-new-list) @@ -784,9 +788,12 @@ Its anaphoric counterpart is `--keep`. (--keep (and (> it 3) (* 10 it)) '(1 2 3 4 5 6)) ;; => (40 50 60) ``` -#### -concat `(&rest lists)` +#### -concat `(&rest sequences)` -Return a new list with the concatenation of the elements in the supplied `lists`. +Concatenate all the arguments and make the result a list. +The result is a list whose elements are the elements of all the arguments. +Each argument may be a list, vector or string. +The last argument is not copied, just used as the tail of the new list. ```el (-concat '(1)) ;; => (1) @@ -893,7 +900,9 @@ See also: [`-replace`](#-replace-old-new-list) #### -update-at `(n func list)` -Return a list with element at `n`th position in `list` replaced with `(func (nth n list))`. +Use `func` to update the `n`th element of `list`. +Return a copy of `list` where the `n`th element is replaced with the +result of calling `func` on it. See also: [`-map-when`](#-map-when-pred-rep-list) @@ -1348,8 +1357,10 @@ Alias: `-none-p` #### -only-some? `(pred list)` -Return `t` if at least one item of `list` matches `pred` and at least one item of `list` does not match `pred`. -Return `nil` both if all items match the predicate or if none of the items match the predicate. +Return t if different `list` items both satisfy and do not satisfy `pred`. +That is, if `pred` returns both nil for at least one item, and +non-nil for at least one other item in `list`. Return nil if all +items satisfy the predicate or none of them do. Alias: `-only-some-p` @@ -1460,7 +1471,14 @@ is done in a single list traversal. #### -split-with `(pred list)` -Return a list of ((-take-while `pred` `list`) (-drop-while `pred` `list`)), in no more than one pass through the list. +Split `list` into a prefix satisfying `pred`, and the rest. +The first sublist is the prefix of `list` with successive elements +satisfying `pred`, and the second sublist is the remaining elements +that do not. The result is like performing + + ((-take-while `pred` `list`) (-drop-while `pred` `list`)) + +but in no more than a single pass through `list`. ```el (-split-with 'even? '(1 2 3 4)) ;; => (nil (1 2 3 4)) @@ -1503,7 +1521,12 @@ This function can be thought of as a generalization of #### -separate `(pred list)` -Return a list of ((-filter `pred` `list`) (-remove `pred` `list`)), in one pass through the list. +Split `list` into two sublists based on whether items satisfy `pred`. +The result is like performing + + ((-filter `pred` `list`) (-remove `pred` `list`)) + +but in a single pass through `list`. ```el (-separate (lambda (num) (= 0 (% num 2))) '(1 2 3 4 5 6 7)) ;; => ((2 4 6) (1 3 5 7)) @@ -1536,9 +1559,9 @@ The last group may contain less than `n` items. #### -partition-in-steps `(n step list)` -Return a new list with the items in `list` grouped into `n`-sized sublists at offsets `step` apart. -If there are not enough items to make the last group `n`-sized, -those items are discarded. +Partition `list` into sublists of length `n` that are `step` items apart. +Like [`-partition-all-in-steps`](#-partition-all-in-steps-n-step-list), but if there are not enough items +to make the last group `n`-sized, those items are discarded. ```el (-partition-in-steps 2 1 '(1 2 3 4)) ;; => ((1 2) (2 3) (3 4)) @@ -1548,8 +1571,9 @@ those items are discarded. #### -partition-all-in-steps `(n step list)` -Return a new list with the items in `list` grouped into `n`-sized sublists at offsets `step` apart. -The last groups may contain less than `n` items. +Partition `list` into sublists of length `n` that are `step` items apart. +Adjacent groups may overlap if `n` exceeds the `step` stride. +Trailing groups may contain less than `n` items. ```el (-partition-all-in-steps 2 1 '(1 2 3 4)) ;; => ((1 2) (2 3) (3 4) (4)) @@ -1728,9 +1752,9 @@ Operations pretending lists are sets. #### -union `(list list2)` -Return a new list containing the elements of `list` and elements of `list2` that are not in `list`. -The test for equality is done with `equal`, -or with `-compare-fn` if that's non-nil. +Return a new list of all elements appearing in either `list1` or `list2`. +Equality is defined by the value of `-compare-fn` if non-nil; +otherwise `equal`. ```el (-union '(1 2 3) '(3 4 5)) ;; => (1 2 3 4 5) @@ -1752,9 +1776,9 @@ or with `-compare-fn` if that's non-nil. #### -intersection `(list list2)` -Return a new list containing only the elements that are members of both `list` and `list2`. -The test for equality is done with `equal`, -or with `-compare-fn` if that's non-nil. +Return a new list of the elements appearing in both `list1` and `list2`. +Equality is defined by the value of `-compare-fn` if non-nil; +otherwise `equal`. ```el (-intersection () ()) ;; => () @@ -3075,18 +3099,36 @@ In types: (a -> a) -> a -> a. #### -prodfn `(&rest fns)` -Take a list of n functions and return a function that takes a -list of length n, applying i-th function to i-th element of the -input list. Returns a list of length n. +Return a function that applies each of `fns` to each of a list of arguments. + +Takes a list of `n` functions and returns a function that takes a +list of length `n`, applying `i`th function to `i`th element of the +input list. Returns a list of length `n`. -In types (for n=2): ((a -> b), (c -> d)) -> (a, c) -> (b, d) +In types (for `n`=2): ((a -> b), (c -> d)) -> (a, c) -> (b, d) This function satisfies the following laws: - (-compose (-prodfn f g ...) (-prodfn f' g' ...)) = (-prodfn (-compose f f') (-compose g g') ...) - (-prodfn f g ...) = (-juxt (-compose f (-partial 'nth 0)) (-compose g (-partial 'nth 1)) ...) - (-compose (-prodfn f g ...) (-juxt f' g' ...)) = (-juxt (-compose f f') (-compose g g') ...) - (-compose (-partial 'nth n) (-prod f1 f2 ...)) = (-compose fn (-partial 'nth n)) + (-compose (-prodfn f g ...) + (-prodfn f' g' ...)) + = (-prodfn (-compose f f') + (-compose g g') + ...) + + (-prodfn f g ...) + = (-juxt (-compose f (-partial #'nth 0)) + (-compose g (-partial #'nth 1)) + ...) + + (-compose (-prodfn f g ...) + (-juxt f' g' ...)) + = (-juxt (-compose f f') + (-compose g g') + ...) + + (-compose (-partial #'nth n) + (-prod f1 f2 ...)) + = (-compose fn (-partial #'nth n)) ```el (funcall (-prodfn '1+ '1- 'number-to-string) '(1 2 3)) ;; => (2 1 "3") diff --git a/dash.el b/dash.el index 6386c5f..472ffa5 100644 --- a/dash.el +++ b/dash.el @@ -613,9 +613,9 @@ For a side-effecting variant, see also `-each-indexed'." (nreverse ,r)))) (defun -map-when (pred rep list) - "Return a new list where the elements in LIST that do not match the PRED function -are unchanged, and where the elements in LIST that do match the PRED function are mapped -through the REP function. + "Use PRED to conditionally apply REP to each item in LIST. +Return a copy of LIST where the items for which PRED returns nil +are unchanged, and the rest are mapped through the REP function. Alias: `-replace-where' @@ -626,7 +626,9 @@ See also: `-update-at'" (defalias '--replace-where '--map-when) (defun -map-first (pred rep list) - "Replace first item in LIST satisfying PRED with result of REP called on this item. + "Use PRED to determine the first item in LIST to call REP on. +Return a copy of LIST where the first item for which PRED returns +non-nil is replaced with the result of calling REP on that item. See also: `-map-when', `-replace-first'" (let (front) @@ -643,7 +645,9 @@ See also: `-map-when', `-replace-first'" `(-map-first (lambda (it) ,pred) (lambda (it) (ignore it) ,rep) ,list)) (defun -map-last (pred rep list) - "Replace last item in LIST satisfying PRED with result of REP called on this item. + "Use PRED to determine the last item in LIST to call REP on. +Return a copy of LIST where the last item for which PRED returns +non-nil is replaced with the result of calling REP on that item. See also: `-map-when', `-replace-last'" (nreverse (-map-first pred rep (reverse list)))) @@ -739,10 +743,7 @@ See also: `-flatten'" (setq list (apply #'append (mapcar #'-list list)))) list) -(defun -concat (&rest lists) - "Return a new list with the concatenation of the elements in the supplied LISTS." - (declare (pure t) (side-effect-free t)) - (apply 'append lists)) +(defalias '-concat #'append) (defalias '-copy 'copy-sequence "Create a shallow copy of LIST. @@ -1057,8 +1058,10 @@ Alias: `-none-p'" (---truthy? (and ,y ,n))))) (defun -only-some? (pred list) - "Return `t` if at least one item of LIST matches PRED and at least one item of LIST does not match PRED. -Return `nil` both if all items match the predicate or if none of the items match the predicate. + "Return t if different LIST items both satisfy and do not satisfy PRED. +That is, if PRED returns both nil for at least one item, and +non-nil for at least one other item in LIST. Return nil if all +items satisfy the predicate or none of them do. Alias: `-only-some-p'" (--only-some? (funcall pred it) list)) @@ -1217,11 +1220,15 @@ See also: `-replace'" (nconc (car split-list) (cons x (cdr (cadr split-list)))))) (defun -update-at (n func list) - "Return a list with element at Nth position in LIST replaced with `(func (nth n list))`. + "Use FUNC to update the Nth element of LIST. +Return a copy of LIST where the Nth element is replaced with the +result of calling FUNC on it. See also: `-map-when'" (let ((split-list (-split-at n list))) - (nconc (car split-list) (cons (funcall func (car (cadr split-list))) (cdr (cadr split-list)))))) + (nconc (car split-list) + (cons (funcall func (car (cadr split-list))) + (cdr (cadr split-list)))))) (defmacro --update-at (n form list) "Anaphoric version of `-update-at'." @@ -1270,7 +1277,14 @@ See also: `-remove-at', `-remove'" (list (nreverse ,r) ,l)))) (defun -split-with (pred list) - "Return a list of ((-take-while PRED LIST) (-drop-while PRED LIST)), in no more than one pass through the list." + "Split LIST into a prefix satisfying PRED, and the rest. +The first sublist is the prefix of LIST with successive elements +satisfying PRED, and the second sublist is the remaining elements +that do not. The result is like performing + + ((-take-while PRED LIST) (-drop-while PRED LIST)) + +but in no more than a single pass through LIST." (--split-with (funcall pred it) list)) (defmacro -split-on (item list) @@ -1318,11 +1332,16 @@ This function can be thought of as a generalization of (list (nreverse ,y) (nreverse ,n))))) (defun -separate (pred list) - "Return a list of ((-filter PRED LIST) (-remove PRED LIST)), in one pass through the list." + "Split LIST into two sublists based on whether items satisfy PRED. +The result is like performing + + ((-filter PRED LIST) (-remove PRED LIST)) + +but in a single pass through LIST." (--separate (funcall pred it) list)) (defun dash--partition-all-in-steps-reversed (n step list) - "Used by `-partition-all-in-steps' and `-partition-in-steps'." + "Like `-partition-all-in-steps', but the result is reversed." (when (< step 1) (signal 'wrong-type-argument `("Step size < 1 results in juicy infinite loops" ,step))) @@ -1333,19 +1352,20 @@ This function can be thought of as a generalization of result)) (defun -partition-all-in-steps (n step list) - "Return a new list with the items in LIST grouped into N-sized sublists at offsets STEP apart. -The last groups may contain less than N items." + "Partition LIST into sublists of length N that are STEP items apart. +Adjacent groups may overlap if N exceeds the STEP stride. +Trailing groups may contain less than N items." (declare (pure t) (side-effect-free t)) (nreverse (dash--partition-all-in-steps-reversed n step list))) (defun -partition-in-steps (n step list) - "Return a new list with the items in LIST grouped into N-sized sublists at offsets STEP apart. -If there are not enough items to make the last group N-sized, -those items are discarded." + "Partition LIST into sublists of length N that are STEP items apart. +Like `-partition-all-in-steps', but if there are not enough items +to make the last group N-sized, those items are discarded." (declare (pure t) (side-effect-free t)) (let ((result (dash--partition-all-in-steps-reversed n step list))) (while (and result (< (length (car result)) n)) - (!cdr result)) + (pop result)) (nreverse result))) (defun -partition-all (n list) @@ -1523,7 +1543,8 @@ elements of LIST. Keys are compared by `equal'." (defmacro --zip-with (form list1 list2) "Anaphoric form of `-zip-with'. -The elements in list1 are bound as symbol `it', the elements in list2 as symbol `other'." +Each element in turn of LIST1 is bound to `it', and of LIST2 to +`other', before evaluating FORM." (declare (debug (form form form))) (let ((r (make-symbol "result")) (l1 (make-symbol "list1")) @@ -2611,9 +2632,9 @@ Alias: `-uniq'" (defalias '-uniq '-distinct) (defun -union (list list2) - "Return a new list containing the elements of LIST and elements of LIST2 that are not in LIST. -The test for equality is done with `equal', -or with `-compare-fn' if that's non-nil." + "Return a new list of all elements appearing in either LIST1 or LIST2. +Equality is defined by the value of `-compare-fn' if non-nil; +otherwise `equal'." ;; We fall back to iteration implementation if the comparison ;; function isn't one of `eq', `eql' or `equal'. (let* ((result (reverse list)) @@ -2630,9 +2651,9 @@ or with `-compare-fn' if that's non-nil." (nreverse result))) (defun -intersection (list list2) - "Return a new list containing only the elements that are members of both LIST and LIST2. -The test for equality is done with `equal', -or with `-compare-fn' if that's non-nil." + "Return a new list of the elements appearing in both LIST1 and LIST2. +Equality is defined by the value of `-compare-fn' if non-nil; +otherwise `equal'." (--filter (-contains? list2 it) list)) (defun -difference (list list2) @@ -3316,18 +3337,36 @@ In types: (a -> a) -> a -> a." re))))) (defun -prodfn (&rest fns) - "Take a list of n functions and return a function that takes a -list of length n, applying i-th function to i-th element of the -input list. Returns a list of length n. + "Return a function that applies each of FNS to each of a list of arguments. + +Takes a list of N functions and returns a function that takes a +list of length N, applying Ith function to Ith element of the +input list. Returns a list of length N. -In types (for n=2): ((a -> b), (c -> d)) -> (a, c) -> (b, d) +In types (for N=2): ((a -> b), (c -> d)) -> (a, c) -> (b, d) This function satisfies the following laws: - (-compose (-prodfn f g ...) (-prodfn f\\=' g\\=' ...)) = (-prodfn (-compose f f\\=') (-compose g g\\=') ...) - (-prodfn f g ...) = (-juxt (-compose f (-partial \\='nth 0)) (-compose g (-partial \\='nth 1)) ...) - (-compose (-prodfn f g ...) (-juxt f\\=' g\\=' ...)) = (-juxt (-compose f f\\=') (-compose g g\\=') ...) - (-compose (-partial \\='nth n) (-prod f1 f2 ...)) = (-compose fn (-partial \\='nth n))" + (-compose (-prodfn f g ...) + (-prodfn f\\=' g\\=' ...)) + = (-prodfn (-compose f f\\=') + (-compose g g\\=') + ...) + + (-prodfn f g ...) + = (-juxt (-compose f (-partial #\\='nth 0)) + (-compose g (-partial #\\='nth 1)) + ...) + + (-compose (-prodfn f g ...) + (-juxt f\\=' g\\=' ...)) + = (-juxt (-compose f f\\=') + (-compose g g\\=') + ...) + + (-compose (-partial #\\='nth n) + (-prod f1 f2 ...)) + = (-compose fn (-partial #\\='nth n))" (lambda (x) (-zip-with 'funcall fns x))) ;;; Font lock diff --git a/dash.texi b/dash.texi index f235094..9bcff91 100644 --- a/dash.texi +++ b/dash.texi @@ -260,9 +260,9 @@ This function's anaphoric counterpart is @code{--map}. @anchor{-map-when} @defun -map-when (pred rep list) -Return a new list where the elements in @var{list} that do not match the @var{pred} function -are unchanged, and where the elements in @var{list} that do match the @var{pred} function are mapped -through the @var{rep} function. +Use @var{pred} to conditionally apply @var{rep} to each item in @var{list}. +Return a copy of @var{list} where the items for which @var{pred} returns nil +are unchanged, and the rest are mapped through the @var{rep} function. Alias: @code{-replace-where} @@ -286,7 +286,9 @@ See also: @code{-update-at} (@pxref{-update-at}) @anchor{-map-first} @defun -map-first (pred rep list) -Replace first item in @var{list} satisfying @var{pred} with result of @var{rep} called on this item. +Use @var{pred} to determine the first item in @var{list} to call @var{rep} on. +Return a copy of @var{list} where the first item for which @var{pred} returns +non-nil is replaced with the result of calling @var{rep} on that item. See also: @code{-map-when} (@pxref{-map-when}), @code{-replace-first} (@pxref{-replace-first}) @@ -308,7 +310,9 @@ See also: @code{-map-when} (@pxref{-map-when}), @code{-replace-first} (@pxref{-r @anchor{-map-last} @defun -map-last (pred rep list) -Replace last item in @var{list} satisfying @var{pred} with result of @var{rep} called on this item. +Use @var{pred} to determine the last item in @var{list} to call @var{rep} on. +Return a copy of @var{list} where the last item for which @var{pred} returns +non-nil is replaced with the result of calling @var{rep} on that item. See also: @code{-map-when} (@pxref{-map-when}), @code{-replace-last} (@pxref{-replace-last}) @@ -892,8 +896,11 @@ Its anaphoric counterpart is @code{--keep}. @end defun @anchor{-concat} -@defun -concat (&rest lists) -Return a new list with the concatenation of the elements in the supplied @var{lists}. +@defun -concat (&rest sequences) +Concatenate all the arguments and make the result a list. +The result is a list whose elements are the elements of all the arguments. +Each argument may be a list, vector or string. +The last argument is not copied, just used as the tail of the new list. @example @group @@ -1077,7 +1084,9 @@ See also: @code{-replace} (@pxref{-replace}) @anchor{-update-at} @defun -update-at (n func list) -Return a list with element at Nth position in @var{list} replaced with `(func (nth n list))`. +Use @var{func} to update the Nth element of @var{list}. +Return a copy of @var{list} where the Nth element is replaced with the +result of calling @var{func} on it. See also: @code{-map-when} (@pxref{-map-when}) @@ -1842,8 +1851,10 @@ Alias: @code{-none-p} @anchor{-only-some?} @defun -only-some? (pred list) -Return `t` if at least one item of @var{list} matches @var{pred} and at least one item of @var{list} does not match @var{pred}. -Return `nil` both if all items match the predicate or if none of the items match the predicate. +Return t if different @var{list} items both satisfy and do not satisfy @var{pred}. +That is, if @var{pred} returns both nil for at least one item, and +non-nil for at least one other item in @var{list}. Return nil if all +items satisfy the predicate or none of them do. Alias: @code{-only-some-p} @@ -2035,7 +2046,14 @@ is done in a single list traversal. @anchor{-split-with} @defun -split-with (pred list) -Return a list of ((-take-while @var{pred} @var{list}) (-drop-while @var{pred} @var{list})), in no more than one pass through the list. +Split @var{list} into a prefix satisfying @var{pred}, and the rest. +The first sublist is the prefix of @var{list} with successive elements +satisfying @var{pred}, and the second sublist is the remaining elements +that do not. The result is like performing + + ((-take-while @var{pred} @var{list}) (-drop-while @var{pred} @var{list})) + +but in no more than a single pass through @var{list}. @example @group @@ -2108,7 +2126,12 @@ This function can be thought of as a generalization of @anchor{-separate} @defun -separate (pred list) -Return a list of ((-filter @var{pred} @var{list}) (-remove @var{pred} @var{list})), in one pass through the list. +Split @var{list} into two sublists based on whether items satisfy @var{pred}. +The result is like performing + + ((-filter @var{pred} @var{list}) (-remove @var{pred} @var{list})) + +but in a single pass through @var{list}. @example @group @@ -2171,9 +2194,9 @@ The last group may contain less than @var{n} items. @anchor{-partition-in-steps} @defun -partition-in-steps (n step list) -Return a new list with the items in @var{list} grouped into @var{n}-sized sublists at offsets @var{step} apart. -If there are not enough items to make the last group @var{n}-sized, -those items are discarded. +Partition @var{list} into sublists of length @var{n} that are @var{step} items apart. +Like @code{-partition-all-in-steps} (@pxref{-partition-all-in-steps}), but if there are not enough items +to make the last group @var{n}-sized, those items are discarded. @example @group @@ -2193,8 +2216,9 @@ those items are discarded. @anchor{-partition-all-in-steps} @defun -partition-all-in-steps (n step list) -Return a new list with the items in @var{list} grouped into @var{n}-sized sublists at offsets @var{step} apart. -The last groups may contain less than @var{n} items. +Partition @var{list} into sublists of length @var{n} that are @var{step} items apart. +Adjacent groups may overlap if @var{n} exceeds the @var{step} stride. +Trailing groups may contain less than @var{n} items. @example @group @@ -2519,9 +2543,9 @@ Operations pretending lists are sets. @anchor{-union} @defun -union (list list2) -Return a new list containing the elements of @var{list} and elements of @var{list2} that are not in @var{list}. -The test for equality is done with @code{equal}, -or with @code{-compare-fn} if that's non-nil. +Return a new list of all elements appearing in either @var{list1} or @var{list2}. +Equality is defined by the value of @code{-compare-fn} if non-nil; +otherwise @code{equal}. @example @group @@ -2563,9 +2587,9 @@ or with @code{-compare-fn} if that's non-nil. @anchor{-intersection} @defun -intersection (list list2) -Return a new list containing only the elements that are members of both @var{list} and @var{list2}. -The test for equality is done with @code{equal}, -or with @code{-compare-fn} if that's non-nil. +Return a new list of the elements appearing in both @var{list1} and @var{list2}. +Equality is defined by the value of @code{-compare-fn} if non-nil; +otherwise @code{equal}. @example @group @@ -4638,18 +4662,36 @@ In types: (a -> a) -> a -> a. @anchor{-prodfn} @defun -prodfn (&rest fns) -Take a list of n functions and return a function that takes a -list of length n, applying i-th function to i-th element of the -input list. Returns a list of length n. +Return a function that applies each of @var{fns} to each of a list of arguments. + +Takes a list of @var{n} functions and returns a function that takes a +list of length @var{n}, applying Ith function to Ith element of the +input list. Returns a list of length @var{n}. -In types (for n=2): ((a -> b), (c -> d)) -> (a, c) -> (b, d) +In types (for @var{n}=2): ((a -> b), (c -> d)) -> (a, c) -> (b, d) This function satisfies the following laws: - (-compose (-prodfn f g @dots{}) (-prodfn f' g' @dots{})) = (-prodfn (-compose f f') (-compose g g') @dots{}) - (-prodfn f g @dots{}) = (-juxt (-compose f (-partial 'nth 0)) (-compose g (-partial 'nth 1)) @dots{}) - (-compose (-prodfn f g @dots{}) (-juxt f' g' @dots{})) = (-juxt (-compose f f') (-compose g g') @dots{}) - (-compose (-partial 'nth n) (-prod f1 f2 @dots{})) = (-compose fn (-partial 'nth n)) + (-compose (-prodfn f g @dots{}) + (-prodfn f' g' @dots{})) + = (-prodfn (-compose f f') + (-compose g g') + @dots{}) + + (-prodfn f g @dots{}) + = (-juxt (-compose f (-partial #'nth 0)) + (-compose g (-partial #'nth 1)) + @dots{}) + + (-compose (-prodfn f g @dots{}) + (-juxt f' g' @dots{})) + = (-juxt (-compose f f') + (-compose g g') + @dots{}) + + (-compose (-partial #'nth n) + (-prod f1 f2 @dots{})) + = (-compose fn (-partial #'nth n)) @example @group diff --git a/dev/examples.el b/dev/examples.el index 480304e..fccda8b 100644 --- a/dev/examples.el +++ b/dev/examples.el @@ -852,6 +852,10 @@ value rather than consuming a list to produce a single value." (-partition-all-in-steps 2 1 '(1 2 3 4)) => '((1 2) (2 3) (3 4) (4)) (-partition-all-in-steps 3 2 '(1 2 3 4)) => '((1 2 3) (3 4)) (-partition-all-in-steps 3 2 '(1 2 3 4 5)) => '((1 2 3) (3 4 5) (5)) + (-partition-all-in-steps 4 2 '(0 1 2 3 4 5 6)) => '((0 1 2 3) + (2 3 4 5) + (4 5 6) + (6)) (-partition-all-in-steps 2 1 '(1)) => '((1)) (-partition-all-in-steps 2 0 '(1)) !!> wrong-type-argument (-partition-all-in-steps 2 -1 '(1)) !!> wrong-type-argument)