wilderjds
/
dash.el
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Fix overly wide docstrings

Browse Source 
* 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.
master
Basil L. Contovounesios 4 years ago
parent 559315ff5a
commit dc61f46417
No known key found for this signature in database
GPG Key ID: 205AB54A5D5D8CFF
4 changed files with 227 additions and 100 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 106
      README.md
  2. 113
      dash.el
  3. 104
      dash.texi
  4. 4
      dev/examples.el

106
README.md
Unescape View File

@ -165,7 +165,7 @@ Functions returning a sublist of the original list.
Functions returning a modified copy of the input list. Functions returning a modified copy of the input list.
* [`-keep`](#-keep-fn-list) `(fn list)` * [`-keep`](#-keep-fn-list) `(fn list)`
* [`-concat`](#-concat-rest-lists) `(&rest lists)` * [`-concat`](#-concat-rest-sequences) `(&rest sequences)`
* [`-flatten`](#-flatten-l) `(l)` * [`-flatten`](#-flatten-l) `(l)`
* [`-flatten-n`](#-flatten-n-num-list) `(num list)` * [`-flatten-n`](#-flatten-n-num-list) `(num list)`
* [`-replace`](#-replace-old-new-list) `(old new 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)` #### -map-when `(pred rep list)`
Return a new list where the elements in `list` that do not match the `pred` function Use `pred` to conditionally apply `rep` to each item in `list`.
are unchanged, and where the elements in `list` that do match the `pred` function are mapped Return a copy of `list` where the items for which `pred` returns nil
through the `rep` function. are unchanged, and the rest are mapped through the `rep` function.
Alias: `-replace-where` Alias: `-replace-where`
@ -422,7 +422,9 @@ See also: [`-update-at`](#-update-at-n-func-list)
#### -map-first `(pred rep 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) 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)` #### -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) 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) (--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 ```el
(-concat '(1)) ;; => (1) (-concat '(1)) ;; => (1)
@ -893,7 +900,9 @@ See also: [`-replace`](#-replace-old-new-list)
#### -update-at `(n func 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) See also: [`-map-when`](#-map-when-pred-rep-list)
@ -1348,8 +1357,10 @@ Alias: `-none-p`
#### -only-some? `(pred list)` #### -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 t if different `list` items both satisfy and do not satisfy `pred`.
Return `nil` both if all items match the predicate or if none of the items match the predicate. 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` Alias: `-only-some-p`
@ -1460,7 +1471,14 @@ is done in a single list traversal.
#### -split-with `(pred list)` #### -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 ```el
(-split-with 'even? '(1 2 3 4)) ;; => (nil (1 2 3 4)) (-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)` #### -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 ```el
(-separate (lambda (num) (= 0 (% num 2))) '(1 2 3 4 5 6 7)) ;; => ((2 4 6) (1 3 5 7)) (-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)` #### -partition-in-steps `(n step list)`
Return a new list with the items in `list` grouped into `n`-sized sublists at offsets `step` apart. Partition `list` into sublists of length `n` that are `step` items apart.
If there are not enough items to make the last group `n`-sized, Like [`-partition-all-in-steps`](#-partition-all-in-steps-n-step-list), but if there are not enough items
those items are discarded. to make the last group `n`-sized, those items are discarded.
```el ```el
(-partition-in-steps 2 1 '(1 2 3 4)) ;; => ((1 2) (2 3) (3 4)) (-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)` #### -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. Partition `list` into sublists of length `n` that are `step` items apart.
The last groups may contain less than `n` items. Adjacent groups may overlap if `n` exceeds the `step` stride.
Trailing groups may contain less than `n` items.
```el ```el
(-partition-all-in-steps 2 1 '(1 2 3 4)) ;; => ((1 2) (2 3) (3 4) (4)) (-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)` #### -union `(list list2)`
Return a new list containing the elements of `list` and elements of `list2` that are not in `list`. Return a new list of all elements appearing in either `list1` or `list2`.
The test for equality is done with `equal`, Equality is defined by the value of `-compare-fn` if non-nil;
or with `-compare-fn` if that's non-nil. otherwise `equal`.
```el ```el
(-union '(1 2 3) '(3 4 5)) ;; => (1 2 3 4 5) (-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)` #### -intersection `(list list2)`
Return a new list containing only the elements that are members of both `list` and `list2`. Return a new list of the elements appearing in both `list1` and `list2`.
The test for equality is done with `equal`, Equality is defined by the value of `-compare-fn` if non-nil;
or with `-compare-fn` if that's non-nil. otherwise `equal`.
```el ```el
(-intersection () ()) ;; => () (-intersection () ()) ;; => ()
@ -3075,18 +3099,36 @@ In types: (a -> a) -> a -> a.
#### -prodfn `(&rest fns)` #### -prodfn `(&rest fns)`
Take a list of n functions and return a function that takes a Return a function that applies each of `fns` to each of a list of arguments.
list of length n, applying i-th function to i-th element of the
input list. Returns a list of length n. 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: This function satisfies the following laws:
(-compose (-prodfn f g ...) (-prodfn f' g' ...)) = (-prodfn (-compose f f') (-compose g g') ...) (-compose (-prodfn f g ...)
(-prodfn f g ...) = (-juxt (-compose f (-partial 'nth 0)) (-compose g (-partial 'nth 1)) ...) (-prodfn f' g' ...))
(-compose (-prodfn f g ...) (-juxt f' g' ...)) = (-juxt (-compose f f') (-compose g g') ...) = (-prodfn (-compose f f')
(-compose (-partial 'nth n) (-prod f1 f2 ...)) = (-compose fn (-partial 'nth n)) (-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 ```el
(funcall (-prodfn '1+ '1- 'number-to-string) '(1 2 3)) ;; => (2 1 "3") (funcall (-prodfn '1+ '1- 'number-to-string) '(1 2 3)) ;; => (2 1 "3")

113
dash.el
Unescape View File

@ -613,9 +613,9 @@ For a side-effecting variant, see also `-each-indexed'."
(nreverse ,r)))) (nreverse ,r))))
(defun -map-when (pred rep list) (defun -map-when (pred rep list)
"Return a new list where the elements in LIST that do not match the PRED function "Use PRED to conditionally apply REP to each item in LIST.
are unchanged, and where the elements in LIST that do match the PRED function are mapped Return a copy of LIST where the items for which PRED returns nil
through the REP function. are unchanged, and the rest are mapped through the REP function.
Alias: `-replace-where' Alias: `-replace-where'
@ -626,7 +626,9 @@ See also: `-update-at'"
(defalias '--replace-where '--map-when) (defalias '--replace-where '--map-when)
(defun -map-first (pred rep list) (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'" See also: `-map-when', `-replace-first'"
(let (front) (let (front)
@ -643,7 +645,9 @@ See also: `-map-when', `-replace-first'"
`(-map-first (lambda (it) ,pred) (lambda (it) (ignore it) ,rep) ,list)) `(-map-first (lambda (it) ,pred) (lambda (it) (ignore it) ,rep) ,list))
(defun -map-last (pred 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'" See also: `-map-when', `-replace-last'"
(nreverse (-map-first pred rep (reverse list)))) (nreverse (-map-first pred rep (reverse list))))
@ -739,10 +743,7 @@ See also: `-flatten'"
(setq list (apply #'append (mapcar #'-list list)))) (setq list (apply #'append (mapcar #'-list list))))
list) list)
(defun -concat (&rest lists) (defalias '-concat #'append)
"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 '-copy 'copy-sequence (defalias '-copy 'copy-sequence
"Create a shallow copy of LIST. "Create a shallow copy of LIST.
@ -1057,8 +1058,10 @@ Alias: `-none-p'"
(---truthy? (and ,y ,n))))) (---truthy? (and ,y ,n)))))
(defun -only-some? (pred list) (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 t if different LIST items both satisfy and do not satisfy PRED.
Return `nil` both if all items match the predicate or if none of the items match the predicate. 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'" Alias: `-only-some-p'"
(--only-some? (funcall pred it) list)) (--only-some? (funcall pred it) list))
@ -1217,11 +1220,15 @@ See also: `-replace'"
(nconc (car split-list) (cons x (cdr (cadr split-list)))))) (nconc (car split-list) (cons x (cdr (cadr split-list))))))
(defun -update-at (n func 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'" See also: `-map-when'"
(let ((split-list (-split-at n list))) (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) (defmacro --update-at (n form list)
"Anaphoric version of `-update-at'." "Anaphoric version of `-update-at'."
@ -1270,7 +1277,14 @@ See also: `-remove-at', `-remove'"
(list (nreverse ,r) ,l)))) (list (nreverse ,r) ,l))))
(defun -split-with (pred list) (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)) (--split-with (funcall pred it) list))
(defmacro -split-on (item 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))))) (list (nreverse ,y) (nreverse ,n)))))
(defun -separate (pred list) (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)) (--separate (funcall pred it) list))
(defun dash--partition-all-in-steps-reversed (n step 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) (when (< step 1)
(signal 'wrong-type-argument (signal 'wrong-type-argument
`("Step size < 1 results in juicy infinite loops" ,step))) `("Step size < 1 results in juicy infinite loops" ,step)))
@ -1333,19 +1352,20 @@ This function can be thought of as a generalization of
result)) result))
(defun -partition-all-in-steps (n step list) (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. "Partition LIST into sublists of length N that are STEP items apart.
The last groups may contain less than N items." 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)) (declare (pure t) (side-effect-free t))
(nreverse (dash--partition-all-in-steps-reversed n step list))) (nreverse (dash--partition-all-in-steps-reversed n step list)))
(defun -partition-in-steps (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. "Partition LIST into sublists of length N that are STEP items apart.
If there are not enough items to make the last group N-sized, Like `-partition-all-in-steps', but if there are not enough items
those items are discarded." to make the last group N-sized, those items are discarded."
(declare (pure t) (side-effect-free t)) (declare (pure t) (side-effect-free t))
(let ((result (dash--partition-all-in-steps-reversed n step list))) (let ((result (dash--partition-all-in-steps-reversed n step list)))
(while (and result (< (length (car result)) n)) (while (and result (< (length (car result)) n))
(!cdr result)) (pop result))
(nreverse result))) (nreverse result)))
(defun -partition-all (n list) (defun -partition-all (n list)
@ -1523,7 +1543,8 @@ elements of LIST. Keys are compared by `equal'."
(defmacro --zip-with (form list1 list2) (defmacro --zip-with (form list1 list2)
"Anaphoric form of `-zip-with'. "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))) (declare (debug (form form form)))
(let ((r (make-symbol "result")) (let ((r (make-symbol "result"))
(l1 (make-symbol "list1")) (l1 (make-symbol "list1"))
@ -2611,9 +2632,9 @@ Alias: `-uniq'"
(defalias '-uniq '-distinct) (defalias '-uniq '-distinct)
(defun -union (list list2) (defun -union (list list2)
"Return a new list containing the elements of LIST and elements of LIST2 that are not in LIST. "Return a new list of all elements appearing in either LIST1 or LIST2.
The test for equality is done with `equal', Equality is defined by the value of `-compare-fn' if non-nil;
or with `-compare-fn' if that's non-nil." otherwise `equal'."
;; We fall back to iteration implementation if the comparison ;; We fall back to iteration implementation if the comparison
;; function isn't one of `eq', `eql' or `equal'. ;; function isn't one of `eq', `eql' or `equal'.
(let* ((result (reverse list)) (let* ((result (reverse list))
@ -2630,9 +2651,9 @@ or with `-compare-fn' if that's non-nil."
(nreverse result))) (nreverse result)))
(defun -intersection (list list2) (defun -intersection (list list2)
"Return a new list containing only the elements that are members of both LIST and LIST2. "Return a new list of the elements appearing in both LIST1 and LIST2.
The test for equality is done with `equal', Equality is defined by the value of `-compare-fn' if non-nil;
or with `-compare-fn' if that's non-nil." otherwise `equal'."
(--filter (-contains? list2 it) list)) (--filter (-contains? list2 it) list))
(defun -difference (list list2) (defun -difference (list list2)
@ -3316,18 +3337,36 @@ In types: (a -> a) -> a -> a."
re))))) re)))))
(defun -prodfn (&rest fns) (defun -prodfn (&rest fns)
"Take a list of n functions and return a function that takes a "Return a function that applies each of FNS to each of a list of arguments.
list of length n, applying i-th function to i-th element of the
input list. Returns a list of length n. 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: This function satisfies the following laws:
(-compose (-prodfn f g ...) (-prodfn f\\=' g\\=' ...)) = (-prodfn (-compose f f\\=') (-compose g g\\=') ...) (-compose (-prodfn f g ...)
(-prodfn f g ...) = (-juxt (-compose f (-partial \\='nth 0)) (-compose g (-partial \\='nth 1)) ...) (-prodfn f\\=' g\\=' ...))
(-compose (-prodfn f g ...) (-juxt f\\=' g\\=' ...)) = (-juxt (-compose f f\\=') (-compose g g\\=') ...) = (-prodfn (-compose f f\\=')
(-compose (-partial \\='nth n) (-prod f1 f2 ...)) = (-compose fn (-partial \\='nth n))" (-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))) (lambda (x) (-zip-with 'funcall fns x)))
;;; Font lock ;;; Font lock

104
dash.texi
Unescape View File

@ -260,9 +260,9 @@ This function's anaphoric counterpart is @code{--map}.
@anchor{-map-when} @anchor{-map-when}
@defun -map-when (pred rep list) @defun -map-when (pred rep list)
Return a new list where the elements in @var{list} that do not match the @var{pred} function Use @var{pred} to conditionally apply @var{rep} to each item in @var{list}.
are unchanged, and where the elements in @var{list} that do match the @var{pred} function are mapped Return a copy of @var{list} where the items for which @var{pred} returns nil
through the @var{rep} function. are unchanged, and the rest are mapped through the @var{rep} function.
Alias: @code{-replace-where} Alias: @code{-replace-where}
@ -286,7 +286,9 @@ See also: @code{-update-at} (@pxref{-update-at})
@anchor{-map-first} @anchor{-map-first}
@defun -map-first (pred rep list) @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}) 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} @anchor{-map-last}
@defun -map-last (pred rep list) @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}) 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 @end defun
@anchor{-concat} @anchor{-concat}
@defun -concat (&rest lists) @defun -concat (&rest sequences)
Return a new list with the concatenation of the elements in the supplied @var{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.
@example @example
@group @group
@ -1077,7 +1084,9 @@ See also: @code{-replace} (@pxref{-replace})
@anchor{-update-at} @anchor{-update-at}
@defun -update-at (n func list) @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}) See also: @code{-map-when} (@pxref{-map-when})
@ -1842,8 +1851,10 @@ Alias: @code{-none-p}
@anchor{-only-some?} @anchor{-only-some?}
@defun -only-some? (pred list) @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 t if different @var{list} items both satisfy and do not satisfy @var{pred}.
Return `nil` both if all items match the predicate or if none of the items match the predicate. 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} Alias: @code{-only-some-p}
@ -2035,7 +2046,14 @@ is done in a single list traversal.
@anchor{-split-with} @anchor{-split-with}
@defun -split-with (pred list) @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 @example
@group @group
@ -2108,7 +2126,12 @@ This function can be thought of as a generalization of
@anchor{-separate} @anchor{-separate}
@defun -separate (pred list) @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 @example
@group @group
@ -2171,9 +2194,9 @@ The last group may contain less than @var{n} items.
@anchor{-partition-in-steps} @anchor{-partition-in-steps}
@defun -partition-in-steps (n step list) @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. Partition @var{list} into sublists of length @var{n} that are @var{step} items apart.
If there are not enough items to make the last group @var{n}-sized, Like @code{-partition-all-in-steps} (@pxref{-partition-all-in-steps}), but if there are not enough items
those items are discarded. to make the last group @var{n}-sized, those items are discarded.
@example @example
@group @group
@ -2193,8 +2216,9 @@ those items are discarded.
@anchor{-partition-all-in-steps} @anchor{-partition-all-in-steps}
@defun -partition-all-in-steps (n step list) @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. Partition @var{list} into sublists of length @var{n} that are @var{step} items apart.
The last groups may contain less than @var{n} items. Adjacent groups may overlap if @var{n} exceeds the @var{step} stride.
Trailing groups may contain less than @var{n} items.
@example @example
@group @group
@ -2519,9 +2543,9 @@ Operations pretending lists are sets.
@anchor{-union} @anchor{-union}
@defun -union (list list2) @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}. Return a new list of all elements appearing in either @var{list1} or @var{list2}.
The test for equality is done with @code{equal}, Equality is defined by the value of @code{-compare-fn} if non-nil;
or with @code{-compare-fn} if that's non-nil. otherwise @code{equal}.
@example @example
@group @group
@ -2563,9 +2587,9 @@ or with @code{-compare-fn} if that's non-nil.
@anchor{-intersection} @anchor{-intersection}
@defun -intersection (list list2) @defun -intersection (list list2)
Return a new list containing only the elements that are members of both @var{list} and @var{list2}. Return a new list of the elements appearing in both @var{list1} and @var{list2}.
The test for equality is done with @code{equal}, Equality is defined by the value of @code{-compare-fn} if non-nil;
or with @code{-compare-fn} if that's non-nil. otherwise @code{equal}.
@example @example
@group @group
@ -4638,18 +4662,36 @@ In types: (a -> a) -> a -> a.
@anchor{-prodfn} @anchor{-prodfn}
@defun -prodfn (&rest fns) @defun -prodfn (&rest fns)
Take a list of n functions and return a function that takes a Return a function that applies each of @var{fns} to each of a list of arguments.
list of length n, applying i-th function to i-th element of the
input list. Returns a list of length n. 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: This function satisfies the following laws:
(-compose (-prodfn f g @dots{}) (-prodfn f' g' @dots{})) = (-prodfn (-compose f f') (-compose g g') @dots{}) (-compose (-prodfn f g @dots{})
(-prodfn f g @dots{}) = (-juxt (-compose f (-partial 'nth 0)) (-compose g (-partial 'nth 1)) @dots{}) (-prodfn f' g' @dots{}))
(-compose (-prodfn f g @dots{}) (-juxt f' g' @dots{})) = (-juxt (-compose f f') (-compose g g') @dots{}) = (-prodfn (-compose f f')
(-compose (-partial 'nth n) (-prod f1 f2 @dots{})) = (-compose fn (-partial 'nth n)) (-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 @example
@group @group

4
dev/examples.el
Unescape View File

@ -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 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)) => '((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 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 1 '(1)) => '((1))
(-partition-all-in-steps 2 0 '(1)) !!> wrong-type-argument (-partition-all-in-steps 2 0 '(1)) !!> wrong-type-argument
(-partition-all-in-steps 2 -1 '(1)) !!> wrong-type-argument) (-partition-all-in-steps 2 -1 '(1)) !!> wrong-type-argument)

Write Preview
Loading…
Cancel
Save