[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/dash c6b92ae 324/439: Reorder the examples into more me
From: |
Phillip Lord |
Subject: |
[elpa] externals/dash c6b92ae 324/439: Reorder the examples into more meaningful blocks |
Date: |
Tue, 04 Aug 2015 20:29:41 +0000 |
branch: externals/dash
commit c6b92ae2ca83dfe626f4e12ef3e539841bd5894c
Author: Matus Goljer <address@hidden>
Commit: Matus Goljer <address@hidden>
Reorder the examples into more meaningful blocks
Add aliases, add links to similar functions to docs to improve
discoverability
Replace 3rd person docstrings with infinitive docstrings.
---
README.md | 459 +++++++++++++++++++++++++++++++++++--------------------
dash.el | 230 ++++++++++++++++------------
dev/examples.el | 159 +++++++++++--------
3 files changed, 517 insertions(+), 331 deletions(-)
diff --git a/README.md b/README.md
index fe383ae..ade7fd3 100644
--- a/README.md
+++ b/README.md
@@ -35,27 +35,46 @@ Include this in your emacs settings to get syntax
highlighting:
## Functions
-### List to list
+### Maps
+
+
+Functions in this category take a transforming function, which
+is then applied sequentially to each or selected elements of the
+input list. The results are collected in order and returned as
+new list.
* [-map](#-map-fn-list) `(fn list)`
-* [-filter](#-filter-pred-list) `(pred list)`
-* [-remove](#-remove-pred-list) `(pred list)`
-* [-keep](#-keep-fn-list) `(fn list)`
* [-map-when](#-map-when-pred-rep-list) `(pred rep list)`
-* [-replace](#-replace-old-new-list) `(old new list)`
* [-map-indexed](#-map-indexed-fn-list) `(fn list)`
+* [-annotate](#-annotate-fn-list) `(fn list)`
* [-splice](#-splice-pred-fun-list) `(pred fun list)`
* [-splice-list](#-splice-list-pred-new-list-list) `(pred new-list list)`
-* [-flatten](#-flatten-l) `(l)`
-* [-flatten-n](#-flatten-n-num-list) `(num list)`
-* [-concat](#-concat-rest-lists) `(&rest lists)`
* [-mapcat](#-mapcat-fn-list) `(fn list)`
+
+### Sublist selection
+
+
+Functions returning a sublist of the original list.
+
+* [-filter](#-filter-pred-list) `(pred list)`
+* [-remove](#-remove-pred-list) `(pred list)`
* [-slice](#-slice-list-from-optional-to-step) `(list from &optional to step)`
* [-take](#-take-n-list) `(n list)`
* [-drop](#-drop-n-list) `(n list)`
* [-take-while](#-take-while-pred-list) `(pred list)`
* [-drop-while](#-drop-while-pred-list) `(pred list)`
-* [-rotate](#-rotate-n-list) `(n list)`
+* [-select-by-indices](#-select-by-indices-indices-list) `(indices list)`
+
+### List to list
+
+
+Bag of various functions which modify input list.
+
+* [-keep](#-keep-fn-list) `(fn list)`
+* [-concat](#-concat-rest-lists) `(&rest lists)`
+* [-flatten](#-flatten-l) `(l)`
+* [-flatten-n](#-flatten-n-num-list) `(num list)`
+* [-replace](#-replace-old-new-list) `(old new list)`
* [-insert-at](#-insert-at-n-x-list) `(n x list)`
* [-replace-at](#-replace-at-n-x-list) `(n x list)`
* [-update-at](#-update-at-n-func-list) `(n func list)`
@@ -64,6 +83,9 @@ Include this in your emacs settings to get syntax
highlighting:
### Reductions
+
+Functions reducing lists into single value.
+
* [-reduce-from](#-reduce-from-fn-initial-value-list) `(fn initial-value list)`
* [-reduce-r-from](#-reduce-r-from-fn-initial-value-list) `(fn initial-value
list)`
* [-reduce](#-reduce-fn-list) `(fn list)`
@@ -98,6 +120,9 @@ Operations dual to reductions, building lists from seed
value rather than consum
### Partitioning
+
+Functions partitioning the input list into a list of lists.
+
* [-split-at](#-split-at-n-list) `(n list)`
* [-split-with](#-split-with-pred-list) `(pred list)`
* [-split-on](#-split-on-item-list) `(item list)`
@@ -113,17 +138,22 @@ Operations dual to reductions, building lists from seed
value rather than consum
### Indexing
+
+Return indices of elements based on predicates, sort elements by indices etc.
+
* [-elem-index](#-elem-index-elem-list) `(elem list)`
* [-elem-indices](#-elem-indices-elem-list) `(elem list)`
* [-find-index](#-find-index-pred-list) `(pred list)`
* [-find-last-index](#-find-last-index-pred-list) `(pred list)`
* [-find-indices](#-find-indices-pred-list) `(pred list)`
-* [-select-by-indices](#-select-by-indices-indices-list) `(indices list)`
* [-grade-up](#-grade-up-comparator-list) `(comparator list)`
* [-grade-down](#-grade-down-comparator-list) `(comparator list)`
### Set operations
+
+Operations pretending lists are sets.
+
* [-union](#-union-list-list2) `(list list2)`
* [-difference](#-difference-list-list2) `(list list2)`
* [-intersection](#-intersection-list-list2) `(list list2)`
@@ -131,6 +161,10 @@ Operations dual to reductions, building lists from seed
value rather than consum
### Other list operations
+
+Other list functions not fit to be classified elsewhere.
+
+* [-rotate](#-rotate-n-list) `(n list)`
* [-repeat](#-repeat-n-x) `(n x)`
* [-cons*](#-cons-rest-args) `(&rest args)`
* [-snoc](#-snoc-list-elem-rest-elements) `(list elem &rest elements)`
@@ -141,7 +175,6 @@ Operations dual to reductions, building lists from seed
value rather than consum
* [-zip-fill](#-zip-fill-fill-value-rest-lists) `(fill-value &rest lists)`
* [-cycle](#-cycle-list) `(list)`
* [-pad](#-pad-fill-value-rest-lists) `(fill-value &rest lists)`
-* [-annotate](#-annotate-fn-list) `(fn list)`
* [-table](#-table-fn-rest-lists) `(fn &rest lists)`
* [-table-flat](#-table-flat-fn-rest-lists) `(fn &rest lists)`
* [-first](#-first-pred-list) `(pred list)`
@@ -153,6 +186,9 @@ Operations dual to reductions, building lists from seed
value rather than consum
### Tree operations
+
+Functions pretending lists are trees.
+
* [-tree-map](#-tree-map-fn-tree) `(fn tree)`
* [-tree-reduce](#-tree-reduce-fn-tree) `(fn tree)`
* [-tree-reduce-from](#-tree-reduce-from-fn-init-value-tree) `(fn init-value
tree)`
@@ -168,6 +204,9 @@ Operations dual to reductions, building lists from seed
value rather than consum
### Binding
+
+Convenient versions of `let` and `let*` constructs combined with flow control.
+
* [-when-let](#-when-let-var-val-rest-body) `(var-val &rest body)`
* [-when-let*](#-when-let-vars-vals-rest-body) `(vars-vals &rest body)`
* [-if-let](#-if-let-var-val-then-rest-else) `(var-val then &rest else)`
@@ -175,6 +214,9 @@ Operations dual to reductions, building lists from seed
value rather than consum
### Side-effects
+
+Functions iterating over lists for side-effect only.
+
* [-each](#-each-list-fn) `(list fn)`
* [-each-while](#-each-while-list-pred-fn) `(list pred fn)`
* [-dotimes](#-dotimes-num-fn) `(num fn)`
@@ -230,11 +272,17 @@ of course the original can also be written like
which demonstrates the usefulness of both versions.
-## List to list
+## Maps
+
+
+Functions in this category take a transforming function, which
+is then applied sequentially to each or selected elements of the
+input list. The results are collected in order and returned as
+new list.
#### -map `(fn list)`
-Returns a new list consisting of the result of applying `fn` to the items in
`list`.
+Return a new list consisting of the result of applying `fn` to the items in
`list`.
```cl
(-map (lambda (num) (* num num)) '(1 2 3 4)) ;; => '(1 4 9 16)
@@ -242,73 +290,42 @@ Returns a new list consisting of the result of applying
`fn` to the items in `li
(--map (* it it) '(1 2 3 4)) ;; => '(1 4 9 16)
```
-#### -filter `(pred list)`
-
-Returns a new list of the items in `list` for which `pred` returns a non-nil
value.
-
-Alias: `-select`
-
-```cl
-(-filter (lambda (num) (= 0 (% num 2))) '(1 2 3 4)) ;; => '(2 4)
-(-filter 'even? '(1 2 3 4)) ;; => '(2 4)
-(--filter (= 0 (% it 2)) '(1 2 3 4)) ;; => '(2 4)
-```
-
-#### -remove `(pred list)`
-
-Returns a new list of the items in `list` for which `pred` returns nil.
-
-Alias: `-reject`
-
-```cl
-(-remove (lambda (num) (= 0 (% num 2))) '(1 2 3 4)) ;; => '(1 3)
-(-remove 'even? '(1 2 3 4)) ;; => '(1 3)
-(--remove (= 0 (% it 2)) '(1 2 3 4)) ;; => '(1 3)
-```
-
-#### -keep `(fn list)`
-
-Returns a new list of the non-nil results of applying `fn` to the items in
`list`.
-
-```cl
-(-keep 'cdr '((1 2 3) (4 5) (6))) ;; => '((2 3) (5))
-(-keep (lambda (num) (when (> num 3) (* 10 num))) '(1 2 3 4 5 6)) ;; => '(40
50 60)
-(--keep (when (> it 3) (* 10 it)) '(1 2 3 4 5 6)) ;; => '(40 50 60)
-```
-
#### -map-when `(pred rep list)`
-Returns a new list where the elements in `list` that does not match the `pred`
function
+Return a new list where the elements in `list` that does 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.
+Alias: `-replace-where`
+
+See also: `-update-at`
+
```cl
(-map-when 'even? 'square '(1 2 3 4)) ;; => '(1 4 3 16)
(--map-when (> it 2) (* it it) '(1 2 3 4)) ;; => '(1 2 9 16)
(--map-when (= it 2) 17 '(1 2 3 4)) ;; => '(1 17 3 4)
```
-#### -replace `(old new list)`
+#### -map-indexed `(fn list)`
-Replace all `old` items in `list` with `new`.
+Return a new list consisting of the result of (`fn` index item) for each item
in `list`.
-Elements are compared using `equal`.
+In the anaphoric form `--map-indexed`, the index is exposed as `it-index`.
```cl
-(-replace 1 "1" '(1 2 3 4 3 2 1)) ;; => '("1" 2 3 4 3 2 "1")
-(-replace "foo" "bar" '("a" "nice" "foo" "sentence" "about" "foo")) ;; =>
'("a" "nice" "bar" "sentence" "about" "bar")
-(-replace 1 2 nil) ;; => nil
+(-map-indexed (lambda (index item) (- item index)) '(1 2 3 4)) ;; => '(1 1 1 1)
+(--map-indexed (- it it-index) '(1 2 3 4)) ;; => '(1 1 1 1)
```
-#### -map-indexed `(fn list)`
-
-Returns a new list consisting of the result of (`fn` index item) for each item
in `list`.
+#### -annotate `(fn list)`
-In the anaphoric form `--map-indexed`, the index is exposed as `it-index`.
+Return a list of cons cells where each cell is `fn` applied to each
+element of `list` paired with the unmodified element of `list`.
```cl
-(-map-indexed (lambda (index item) (- item index)) '(1 2 3 4)) ;; => '(1 1 1 1)
-(--map-indexed (- it it-index) '(1 2 3 4)) ;; => '(1 1 1 1)
+(-annotate '1+ '(1 2 3)) ;; => '((2 . 1) (3 . 2) (4 . 3))
+(-annotate 'length '(("h" "e" "l" "l" "o") ("hello" "world"))) ;; => '((5 "h"
"e" "l" "l" "o") (2 "hello" "world"))
+(--annotate (< 1 it) '(0 1 2 3)) ;; => '((nil . 0) (nil . 1) (t . 2) (t . 3))
```
#### -splice `(pred fun list)`
@@ -321,6 +338,8 @@ This function can be used as replacement for `,@` in case
you
need to splice several lists at marked positions (for example
with keywords).
+See also: `-splice-list`, `-insert-at`
+
```cl
(-splice 'even? (lambda (x) (list x x)) '(1 2 3 4)) ;; => '(1 2 2 3 4 4)
(--splice 't (list it it) '(1 2 3 4)) ;; => '(1 1 2 2 3 3 4 4)
@@ -331,52 +350,52 @@ with keywords).
Splice `new-list` in place of elements matching `pred` in `list`.
-See also more general version: `-splice`.
+See also: `-splice`, `-insert-at`
```cl
(-splice-list 'keywordp '(a b c) '(1 :foo 2)) ;; => '(1 a b c 2)
(-splice-list 'keywordp nil '(1 :foo 2)) ;; => '(1 2)
```
-#### -flatten `(l)`
+#### -mapcat `(fn list)`
-Takes a nested list `l` and returns its contents as a single, flat list.
+Return the concatenation of the result of mapping `fn` over `list`.
+Thus function `fn` should return a list.
```cl
-(-flatten '((1))) ;; => '(1)
-(-flatten '((1 (2 3) (((4 (5))))))) ;; => '(1 2 3 4 5)
-(-flatten '(1 2 (3 . 4))) ;; => '(1 2 (3 . 4))
+(-mapcat 'list '(1 2 3)) ;; => '(1 2 3)
+(-mapcat (lambda (item) (list 0 item)) '(1 2 3)) ;; => '(0 1 0 2 0 3)
+(--mapcat (list 0 it) '(1 2 3)) ;; => '(0 1 0 2 0 3)
```
-#### -flatten-n `(num list)`
-Flatten `num` levels of a nested `list`.
+## Sublist selection
-```cl
-(-flatten-n 1 '((1 2) ((3 4) ((5 6))))) ;; => '(1 2 (3 4) ((5 6)))
-(-flatten-n 2 '((1 2) ((3 4) ((5 6))))) ;; => '(1 2 3 4 (5 6))
-(-flatten-n 3 '((1 2) ((3 4) ((5 6))))) ;; => '(1 2 3 4 5 6)
-```
-#### -concat `(&rest lists)`
+Functions returning a sublist of the original list.
-Returns a new list with the concatenation of the elements in the supplied
`lists`.
+#### -filter `(pred list)`
+
+Return a new list of the items in `list` for which `pred` returns a non-nil
value.
+
+Alias: `-select`
```cl
-(-concat '(1)) ;; => '(1)
-(-concat '(1) '(2)) ;; => '(1 2)
-(-concat '(1) '(2 3) '(4)) ;; => '(1 2 3 4)
+(-filter (lambda (num) (= 0 (% num 2))) '(1 2 3 4)) ;; => '(2 4)
+(-filter 'even? '(1 2 3 4)) ;; => '(2 4)
+(--filter (= 0 (% it 2)) '(1 2 3 4)) ;; => '(2 4)
```
-#### -mapcat `(fn list)`
+#### -remove `(pred list)`
-Returns the concatenation of the result of mapping `fn` over `list`.
-Thus function `fn` should return a list.
+Return a new list of the items in `list` for which `pred` returns nil.
+
+Alias: `-reject`
```cl
-(-mapcat 'list '(1 2 3)) ;; => '(1 2 3)
-(-mapcat (lambda (item) (list 0 item)) '(1 2 3)) ;; => '(0 1 0 2 0 3)
-(--mapcat (list 0 it) '(1 2 3)) ;; => '(0 1 0 2 0 3)
+(-remove (lambda (num) (= 0 (% num 2))) '(1 2 3 4)) ;; => '(1 3)
+(-remove 'even? '(1 2 3 4)) ;; => '(1 3)
+(--remove (= 0 (% it 2)) '(1 2 3 4)) ;; => '(1 3)
```
#### -slice `(list from &optional to step)`
@@ -397,7 +416,7 @@ section is returned. Defaults to 1.
#### -take `(n list)`
-Returns a new list of the first `n` items in `list`, or all items if there are
fewer than `n`.
+Return a new list of the first `n` items in `list`, or all items if there are
fewer than `n`.
```cl
(-take 3 '(1 2 3 4 5)) ;; => '(1 2 3)
@@ -406,7 +425,7 @@ Returns a new list of the first `n` items in `list`, or all
items if there are f
#### -drop `(n list)`
-Returns the tail of `list` without the first `n` items.
+Return the tail of `list` without the first `n` items.
```cl
(-drop 3 '(1 2 3 4 5)) ;; => '(4 5)
@@ -415,7 +434,7 @@ Returns the tail of `list` without the first `n` items.
#### -take-while `(pred list)`
-Returns a new list of successive items from `list` while (`pred` item) returns
a non-nil value.
+Return a new list of successive items from `list` while (`pred` item) returns
a non-nil value.
```cl
(-take-while 'even? '(1 2 3 4)) ;; => '()
@@ -425,7 +444,7 @@ Returns a new list of successive items from `list` while
(`pred` item) returns a
#### -drop-while `(pred list)`
-Returns the tail of `list` starting from the first item for which (`pred`
item) returns nil.
+Return the tail of `list` starting from the first item for which (`pred` item)
returns nil.
```cl
(-drop-while 'even? '(1 2 3 4)) ;; => '(1 2 3 4)
@@ -433,19 +452,86 @@ Returns the tail of `list` starting from the first item
for which (`pred` item)
(--drop-while (< it 4) '(1 2 3 4 3 2 1)) ;; => '(4 3 2 1)
```
-#### -rotate `(n list)`
+#### -select-by-indices `(indices list)`
-Rotate `list` `n` places to the right. With `n` negative, rotate to the left.
-The time complexity is `o`(n).
+Return a list whose elements are elements from `list` selected
+as `(nth i list)` for all i from `indices`.
```cl
-(-rotate 3 '(1 2 3 4 5 6 7)) ;; => '(5 6 7 1 2 3 4)
-(-rotate -3 '(1 2 3 4 5 6 7)) ;; => '(4 5 6 7 1 2 3)
+(-select-by-indices '(4 10 2 3 6) '("v" "e" "l" "o" "c" "i" "r" "a" "p" "t"
"o" "r")) ;; => '("c" "o" "l" "o" "r")
+(-select-by-indices '(2 1 0) '("a" "b" "c")) ;; => '("c" "b" "a")
+(-select-by-indices '(0 1 2 0 1 3 3 1) '("f" "a" "r" "l")) ;; => '("f" "a" "r"
"f" "a" "l" "l" "a")
+```
+
+
+## List to list
+
+
+Bag of various functions which modify input list.
+
+#### -keep `(fn list)`
+
+Return a new list of the non-nil results of applying `fn` to the items in
`list`.
+
+```cl
+(-keep 'cdr '((1 2 3) (4 5) (6))) ;; => '((2 3) (5))
+(-keep (lambda (num) (when (> num 3) (* 10 num))) '(1 2 3 4 5 6)) ;; => '(40
50 60)
+(--keep (when (> it 3) (* 10 it)) '(1 2 3 4 5 6)) ;; => '(40 50 60)
+```
+
+#### -concat `(&rest lists)`
+
+Return a new list with the concatenation of the elements in the supplied
`lists`.
+
+```cl
+(-concat '(1)) ;; => '(1)
+(-concat '(1) '(2)) ;; => '(1 2)
+(-concat '(1) '(2 3) '(4)) ;; => '(1 2 3 4)
+```
+
+#### -flatten `(l)`
+
+Take a nested list `l` and return its contents as a single, flat list.
+
+See also: `-flatten-n`
+
+```cl
+(-flatten '((1))) ;; => '(1)
+(-flatten '((1 (2 3) (((4 (5))))))) ;; => '(1 2 3 4 5)
+(-flatten '(1 2 (3 . 4))) ;; => '(1 2 (3 . 4))
+```
+
+#### -flatten-n `(num list)`
+
+Flatten `num` levels of a nested `list`.
+
+See also: `-flatten`
+
+```cl
+(-flatten-n 1 '((1 2) ((3 4) ((5 6))))) ;; => '(1 2 (3 4) ((5 6)))
+(-flatten-n 2 '((1 2) ((3 4) ((5 6))))) ;; => '(1 2 3 4 (5 6))
+(-flatten-n 3 '((1 2) ((3 4) ((5 6))))) ;; => '(1 2 3 4 5 6)
+```
+
+#### -replace `(old new list)`
+
+Replace all `old` items in `list` with `new`.
+
+Elements are compared using `equal`.
+
+See also: `-replace-at`
+
+```cl
+(-replace 1 "1" '(1 2 3 4 3 2 1)) ;; => '("1" 2 3 4 3 2 "1")
+(-replace "foo" "bar" '("a" "nice" "foo" "sentence" "about" "foo")) ;; =>
'("a" "nice" "bar" "sentence" "about" "bar")
+(-replace 1 2 nil) ;; => nil
```
#### -insert-at `(n x list)`
-Returns a list with `x` inserted into `list` at position `n`.
+Return a list with `x` inserted into `list` at position `n`.
+
+See also: `-splice`, `-splice-list`
```cl
(-insert-at 1 'x '(a b c)) ;; => '(a x b c)
@@ -456,6 +542,8 @@ Returns a list with `x` inserted into `list` at position
`n`.
Return a list with element at Nth position in `list` replaced with `x`.
+See also: `-replace`
+
```cl
(-replace-at 0 9 '(0 1 2 3 4 5)) ;; => '(9 1 2 3 4 5)
(-replace-at 1 9 '(0 1 2 3 4 5)) ;; => '(0 9 2 3 4 5)
@@ -466,6 +554,8 @@ Return a list with element at Nth position in `list`
replaced with `x`.
Return a list with element at Nth position in `list` replaced with `(func (nth
n list))`.
+See also: `-map-when`
+
```cl
(-update-at 0 (lambda (x) (+ x 9)) '(0 1 2 3 4 5)) ;; => '(9 1 2 3 4 5)
(-update-at 1 (lambda (x) (+ x 8)) '(0 1 2 3 4 5)) ;; => '(0 9 2 3 4 5)
@@ -476,6 +566,8 @@ Return a list with element at Nth position in `list`
replaced with `(func (nth n
Return a list with element at Nth position in `list` removed.
+See also: `-remove-at-indices`, `-remove`
+
```cl
(-remove-at 0 '("0" "1" "2" "3" "4" "5")) ;; => '("1" "2" "3" "4" "5")
(-remove-at 1 '("0" "1" "2" "3" "4" "5")) ;; => '("0" "2" "3" "4" "5")
@@ -488,6 +580,8 @@ Return a list whose elements are elements from `list`
without
elements selected as `(nth i list)` for all i
from `indices`.
+See also: `-remove-at`, `-remove`
+
```cl
(-remove-at-indices '(0) '("0" "1" "2" "3" "4" "5")) ;; => '("1" "2" "3" "4"
"5")
(-remove-at-indices '(0 2 4) '("0" "1" "2" "3" "4" "5")) ;; => '("1" "3" "5")
@@ -497,11 +591,14 @@ from `indices`.
## Reductions
+
+Functions reducing lists into single value.
+
#### -reduce-from `(fn initial-value list)`
-Returns the result of applying `fn` to `initial-value` and the
+Return the result of applying `fn` to `initial-value` and the
first item in `list`, then applying `fn` to that result and the 2nd
-item, etc. If `list` contains no items, returns `initial-value` and
+item, etc. If `list` contains no items, return `initial-value` and
`fn` is not called.
In the anaphoric form `--reduce-from`, the accumulated value is
@@ -530,10 +627,10 @@ operation associates from right instead of from left.
#### -reduce `(fn list)`
-Returns the result of applying `fn` to the first 2 items in `list`,
+Return the result of applying `fn` to the first 2 items in `list`,
then applying `fn` to that result and the 3rd item, etc. If `list`
contains no items, `fn` must accept no arguments as well, and
-reduce returns the result of calling `fn` with no arguments. If
+reduce return the result of calling `fn` with no arguments. If
`list` has only 1 item, it is returned and `fn` is not called.
In the anaphoric form `--reduce`, the accumulated value is
@@ -549,7 +646,7 @@ exposed as `acc`.
Replace conses with `fn` and evaluate the resulting expression.
The final nil is ignored. If `list` contains no items, `fn` must
-accept no arguments as well, and reduce returns the result of
+accept no arguments as well, and reduce return the result of
calling `fn` with no arguments. If `list` has only 1 item, it is
returned and `fn` is not called.
@@ -687,9 +784,9 @@ the new seed.
#### -any? `(pred list)`
-Returns t if (`pred` x) is non-nil for any x in `list`, else nil.
+Return t if (`pred` x) is non-nil for any x in `list`, else nil.
-Alias: `-some?`
+Alias: `-any-p`, `-some?`, `-some-p`
```cl
(-any? 'even? '(1 2 3)) ;; => t
@@ -699,9 +796,9 @@ Alias: `-some?`
#### -all? `(pred list)`
-Returns t if (`pred` x) is non-nil for all x in `list`, else nil.
+Return t if (`pred` x) is non-nil for all x in `list`, else nil.
-Alias: `-every?`
+Alias: `-all-p`, `-every?`, `-every-p`
```cl
(-all? 'even? '(1 2 3)) ;; => nil
@@ -711,7 +808,9 @@ Alias: `-every?`
#### -none? `(pred list)`
-Returns t if (`pred` x) is nil for all x in `list`, else nil.
+Return t if (`pred` x) is nil for all x in `list`, else nil.
+
+Alias: `-none-p`
```cl
(-none? 'even? '(1 2 3)) ;; => nil
@@ -721,8 +820,10 @@ Returns t if (`pred` x) is nil for all x in `list`, else
nil.
#### -only-some? `(pred list)`
-Returns `t` if there is a mix of items in `list` that matches and does not
match `pred`.
-Returns `nil` both if all items match the predicate, and if none of the items
match the predicate.
+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.
+
+Alias: `-only-some-p`
```cl
(-only-some? 'even? '(1 2 3)) ;; => t
@@ -732,9 +833,12 @@ Returns `nil` both if all items match the predicate, and
if none of the items ma
#### -contains? `(list element)`
-Return whether `list` contains `element`.
-The test for equality is done with `equal`,
-or with `-compare-fn` if that's non-nil.
+Return non-nil if `list` contains `element`.
+
+The test for equality is done with `equal`, or with `-compare-fn`
+if that's non-nil.
+
+Alias: `-contains-p`
```cl
(-contains? '(1 2 3) 1) ;; => t
@@ -748,6 +852,8 @@ Return true if `list` and `list2` has the same items.
The order of the elements in the lists does not matter.
+Alias: `-same-items-p`
+
```cl
(-same-items? '(1 2 3) '(1 2 3)) ;; => t
(-same-items? '(1 2 3) '(3 2 1)) ;; => t
@@ -758,6 +864,8 @@ The order of the elements in the lists does not matter.
Return non-nil if `prefix` is prefix of `list`.
+Alias: `-is-prefix-p`
+
```cl
(-is-prefix? '(1 2 3) '(1 2 3 4 5)) ;; => t
(-is-prefix? '(1 2 3 4 5) '(1 2 3)) ;; => nil
@@ -768,6 +876,8 @@ Return non-nil if `prefix` is prefix of `list`.
Return non-nil if `suffix` is suffix of `list`.
+Alias: `-is-suffix-p`
+
```cl
(-is-suffix? '(3 4 5) '(1 2 3 4 5)) ;; => t
(-is-suffix? '(1 2 3 4 5) '(3 4 5)) ;; => nil
@@ -780,6 +890,8 @@ Return non-nil if `infix` is infix of `list`.
This operation runs in `o`(n^2) time
+Alias: `-is-infix-p`
+
```cl
(-is-infix? '(1 2 3) '(1 2 3 4 5)) ;; => t
(-is-infix? '(2 3 4) '(1 2 3 4 5)) ;; => t
@@ -789,9 +901,12 @@ This operation runs in `o`(n^2) time
## Partitioning
+
+Functions partitioning the input list into a list of lists.
+
#### -split-at `(n list)`
-Returns a list of ((-take `n` `list`) (-drop `n` `list`)), in no more than one
pass through the list.
+Return a list of ((-take `n` `list`) (-drop `n` `list`)), in no more than one
pass through the list.
```cl
(-split-at 3 '(1 2 3 4 5)) ;; => '((1 2 3) (4 5))
@@ -800,7 +915,7 @@ Returns a list of ((-take `n` `list`) (-drop `n` `list`)),
in no more than one p
#### -split-with `(pred list)`
-Returns a list of ((-take-while `pred` `list`) (-drop-while `pred` `list`)),
in no more than one pass through the list.
+Return a list of ((-take-while `pred` `list`) (-drop-while `pred` `list`)), in
no more than one pass through the list.
```cl
(-split-with 'even? '(1 2 3 4)) ;; => '(nil (1 2 3 4))
@@ -817,7 +932,7 @@ Empty lists are also removed from the result.
Comparison is done by `equal`.
-See also `-split-when`.
+See also `-split-when`
```cl
(-split-on '| '(Nil | Leaf a | Node [Tree a])) ;; => '((Nil) (Leaf a) (Node
[Tree a]))
@@ -843,7 +958,7 @@ This function can be thought of as a generalization of
#### -separate `(pred list)`
-Returns a list of ((-filter `pred` `list`) (-remove `pred` `list`)), in one
pass through the list.
+Return a list of ((-filter `pred` `list`) (-remove `pred` `list`)), in one
pass through the list.
```cl
(-separate (lambda (num) (= 0 (% num 2))) '(1 2 3 4 5 6 7)) ;; => '((2 4 6) (1
3 5 7))
@@ -853,7 +968,7 @@ Returns a list of ((-filter `pred` `list`) (-remove `pred`
`list`)), in one pass
#### -partition `(n list)`
-Returns a new list with the items in `list` grouped into `n-`sized sublists.
+Return a new list with the items in `list` grouped into `n-`sized sublists.
If there are not enough items to make the last group `n-`sized,
those items are discarded.
@@ -865,7 +980,7 @@ those items are discarded.
#### -partition-all `(n list)`
-Returns a new list with the items in `list` grouped into `n-`sized sublists.
+Return a new list with the items in `list` grouped into `n-`sized sublists.
The last group may contain less than `n` items.
```cl
@@ -876,7 +991,7 @@ The last group may contain less than `n` items.
#### -partition-in-steps `(n step list)`
-Returns a new list with the items in `list` grouped into `n-`sized sublists at
offsets `step` apart.
+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.
@@ -888,7 +1003,7 @@ those items are discarded.
#### -partition-all-in-steps `(n step list)`
-Returns a new list with the items in `list` grouped into `n-`sized sublists at
offsets `step` apart.
+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.
```cl
@@ -899,7 +1014,7 @@ The last groups may contain less than `n` items.
#### -partition-by `(fn list)`
-Applies `fn` to each item in `list`, splitting it each time `fn` returns a new
value.
+Apply `fn` to each item in `list`, splitting it each time `fn` returns a new
value.
```cl
(-partition-by 'even? '()) ;; => '()
@@ -909,8 +1024,8 @@ Applies `fn` to each item in `list`, splitting it each
time `fn` returns a new v
#### -partition-by-header `(fn list)`
-Applies `fn` to the first item in `list`. That is the header
-value. Applies `fn` to each item in `list`, splitting it each time `fn`
+Apply `fn` to the first item in `list`. That is the header
+value. Apply `fn` to each item in `list`, splitting it each time `fn`
returns the header value, but only after seeing at least one
other value (the body).
@@ -934,6 +1049,9 @@ elements of `list`. Keys are compared by `equal`.
## Indexing
+
+Return indices of elements based on predicates, sort elements by indices etc.
+
#### -elem-index `(elem list)`
Return the index of the first element in the given `list` which
@@ -992,20 +1110,9 @@ predicate `pred`, in ascending order.
(-find-indices (-partial 'string-lessp "baz") '("bar" "foo" "baz")) ;; => '(1)
```
-#### -select-by-indices `(indices list)`
-
-Return a list whose elements are elements from `list` selected
-as `(nth i list)` for all i from `indices`.
-
-```cl
-(-select-by-indices '(4 10 2 3 6) '("v" "e" "l" "o" "c" "i" "r" "a" "p" "t"
"o" "r")) ;; => '("c" "o" "l" "o" "r")
-(-select-by-indices '(2 1 0) '("a" "b" "c")) ;; => '("c" "b" "a")
-(-select-by-indices '(0 1 2 0 1 3 3 1) '("f" "a" "r" "l")) ;; => '("f" "a" "r"
"f" "a" "l" "l" "a")
-```
-
#### -grade-up `(comparator list)`
-Grades elements of `list` using `comparator` relation, yielding a
+Grade elements of `list` using `comparator` relation, yielding a
permutation vector such that applying this permutation to `list`
sorts it in ascending order.
@@ -1016,7 +1123,7 @@ sorts it in ascending order.
#### -grade-down `(comparator list)`
-Grades elements of `list` using `comparator` relation, yielding a
+Grade elements of `list` using `comparator` relation, yielding a
permutation vector such that applying this permutation to `list`
sorts it in descending order.
@@ -1028,6 +1135,9 @@ sorts it in descending order.
## Set operations
+
+Operations pretending lists are sets.
+
#### -union `(list list2)`
Return a new list containing the elements of `list1` and elements of `list2`
that are not in `list1`.
@@ -1080,10 +1190,23 @@ Alias: `-uniq`
## Other list operations
+
+Other list functions not fit to be classified elsewhere.
+
+#### -rotate `(n list)`
+
+Rotate `list` `n` places to the right. With `n` negative, rotate to the left.
+The time complexity is `o`(n).
+
+```cl
+(-rotate 3 '(1 2 3 4 5 6 7)) ;; => '(5 6 7 1 2 3 4)
+(-rotate -3 '(1 2 3 4 5 6 7)) ;; => '(4 5 6 7 1 2 3)
+```
+
#### -repeat `(n x)`
Return a list with `x` repeated `n` times.
-Returns nil if `n` is less than 1.
+Return nil if `n` is less than 1.
```cl
(-repeat 3 :a) ;; => '(:a :a :a)
@@ -1093,7 +1216,7 @@ Returns nil if `n` is less than 1.
#### -cons* `(&rest args)`
-Makes a new list from the elements of `args`.
+Make a new list from the elements of `args`.
The last 2 members of `args` are used as the final cons of the
result so if the final member of `args` is not a list the result is
@@ -1121,7 +1244,7 @@ If `elements` is non nil, append these to the list as
well.
#### -interpose `(sep list)`
-Returns a new list of all elements in `list` separated by `sep`.
+Return a new list of all elements in `list` separated by `sep`.
```cl
(-interpose "-" '()) ;; => '()
@@ -1131,7 +1254,7 @@ Returns a new list of all elements in `list` separated by
`sep`.
#### -interleave `(&rest lists)`
-Returns a new list of the first item in each list, then the second etc.
+Return a new list of the first item in each list, then the second etc.
```cl
(-interleave '(1 2) '("a" "b")) ;; => '(1 "a" 2 "b")
@@ -1182,7 +1305,7 @@ longest input list.
#### -cycle `(list)`
-Returns an infinite copy of `list` that will cycle through the
+Return an infinite copy of `list` that will cycle through the
elements and repeat from the beginning.
```cl
@@ -1202,17 +1325,6 @@ will all have the same length.
(-pad 0 '(1 2 3) '(4 5)) ;; => '((1 2 3) (4 5 0))
```
-#### -annotate `(fn list)`
-
-Returns a list of cons cells where each cell is `fn` applied to each
-element of `list` paired with the unmodified element of `list`.
-
-```cl
-(-annotate '1+ '(1 2 3)) ;; => '((2 . 1) (3 . 2) (4 . 3))
-(-annotate 'length '(("h" "e" "l" "l" "o") ("hello" "world"))) ;; => '((5 "h"
"e" "l" "l" "o") (2 "hello" "world"))
-(--annotate (< 1 it) '(0 1 2 3)) ;; => '((nil . 0) (nil . 1) (t . 2) (t . 3))
-```
-
#### -table `(fn &rest lists)`
Compute outer product of `lists` using function `fn`.
@@ -1224,7 +1336,7 @@ The outer product is computed by applying fn to all
possible
combinations created by taking one element from each list in
order. The dimension of the result is (length lists).
-See also: `-table-flat`.
+See also: `-table-flat`
```cl
(-table '* '(1 2 3) '(1 2 3)) ;; => '((1 2 3) (2 4 6) (3 6 9))
@@ -1248,7 +1360,7 @@ of the result. This is equivalent to calling:
but the implementation here is much more efficient.
-See also: `-flatten-n`, `-table`.
+See also: `-flatten-n`, `-table`
```cl
(-table-flat 'list '(1 2 3) '(a b c)) ;; => '((1 a) (2 a) (3 a) (1 b) (2 b) (3
b) (1 c) (2 c) (3 c))
@@ -1258,11 +1370,11 @@ See also: `-flatten-n`, `-table`.
#### -first `(pred list)`
-Returns the first x in `list` where (`pred` x) is non-nil, else nil.
+Return the first x in `list` where (`pred` x) is non-nil, else nil.
To get the first item in the list no questions asked, use `car`.
-This function is also available as `-find`.
+Alias: `-find`
```cl
(-first 'even? '(1 2 3)) ;; => 2
@@ -1282,7 +1394,7 @@ Return the last x in `list` where (`pred` x) is non-nil,
else nil.
#### -first-item `(list)`
-Returns the first item of `list`, or nil on an empty list.
+Return the first item of `list`, or nil on an empty list.
```cl
(-first-item '(1 2 3)) ;; => 1
@@ -1291,7 +1403,7 @@ Returns the first item of `list`, or nil on an empty list.
#### -last-item `(list)`
-Returns the last item of `list`, or nil on an empty list.
+Return the last item of `list`, or nil on an empty list.
```cl
(-last-item '(1 2 3)) ;; => 3
@@ -1301,7 +1413,7 @@ Returns the last item of `list`, or nil on an empty list.
#### -sort `(comparator list)`
Sort `list`, stably, comparing elements using `comparator`.
-Returns the sorted list. `list` is `not` modified by side effects.
+Return the sorted list. `list` is `not` modified by side effects.
`comparator` is called with two elements of `list`, and should return non-nil
if the first element should sort before the second.
@@ -1326,6 +1438,9 @@ not, return a list with `args` as elements.
## Tree operations
+
+Functions pretending lists are trees.
+
#### -tree-map `(fn tree)`
Apply `fn` to each element of `tree` while preserving the tree structure.
@@ -1420,9 +1535,9 @@ structure such as plist or alist.
#### -> `(x &optional form &rest more)`
-Threads the expr through the forms. Inserts `x` as the second
-item in the first form, making a list of it if it is not a list
-already. If there are more forms, inserts the first form as the
+Thread the expr through the forms. Insert `x` as the second item
+in the first form, making a list of it if it is not a list
+already. If there are more forms, insert the first form as the
second item in second form, etc.
```cl
@@ -1433,9 +1548,9 @@ second item in second form, etc.
#### ->> `(x form &rest more)`
-Threads the expr through the forms. Inserts `x` as the last item
+Thread the expr through the forms. Insert `x` as the last item
in the first form, making a list of it if it is not a list
-already. If there are more forms, inserts the first form as the
+already. If there are more forms, insert the first form as the
last item in second form, etc.
```cl
@@ -1446,10 +1561,10 @@ last item in second form, etc.
#### --> `(x form &rest more)`
-Threads the expr through the forms. Inserts `x` at the position
+Thread the expr through the forms. Insert `x` at the position
signified by the token `it` in the first form. If there are more
-forms, inserts the first form at the position signified by `it`
-in in second form, etc.
+forms, insert the first form at the position signified by `it` in
+in second form, etc.
```cl
(--> "def" (concat "abc" it "ghi")) ;; => "abcdefghi"
@@ -1460,6 +1575,9 @@ in in second form, etc.
## Binding
+
+Convenient versions of `let` and `let*` constructs combined with flow control.
+
#### -when-let `(var-val &rest body)`
If `val` evaluates to non-nil, bind it to `var` and execute body.
@@ -1506,9 +1624,12 @@ of (`var` `val`) pairs (corresponding to the bindings of
`let*`).
## Side-effects
+
+Functions iterating over lists for side-effect only.
+
#### -each `(list fn)`
-Calls `fn` with every item in `list`. Returns nil, used for side-effects only.
+Call `fn` with every item in `list`. Return nil, used for side-effects only.
```cl
(let (s) (-each '(1 2 3) (lambda (item) (setq s (cons item s))))) ;; => nil
@@ -1518,8 +1639,8 @@ Calls `fn` with every item in `list`. Returns nil, used
for side-effects only.
#### -each-while `(list pred fn)`
-Calls `fn` with every item in `list` while (`pred` item) is non-nil.
-Returns nil, used for side-effects only.
+Call `fn` with every item in `list` while (`pred` item) is non-nil.
+Return nil, used for side-effects only.
```cl
(let (s) (-each-while '(2 4 5 6) 'even? (lambda (item) (!cons item s))) s) ;;
=> '(4 2)
@@ -1540,7 +1661,7 @@ Repeatedly calls `fn` (presumably for side-effects)
passing in integers from 0 t
#### !cons `(car cdr)`
-Destructive: Sets `cdr` to the cons of `car` and `cdr`.
+Destructive: Set `cdr` to the cons of `car` and `cdr`.
```cl
(let (l) (!cons 5 l) l) ;; => '(5)
@@ -1549,7 +1670,7 @@ Destructive: Sets `cdr` to the cons of `car` and `cdr`.
#### !cdr `(list)`
-Destructive: Sets `list` to the cdr of `list`.
+Destructive: Set `list` to the cdr of `list`.
```cl
(let ((l '(3))) (!cdr l) l) ;; => '()
diff --git a/dash.el b/dash.el
index 775e799..d0aae94 100644
--- a/dash.el
+++ b/dash.el
@@ -45,11 +45,11 @@ special values."
:group 'dash)
(defmacro !cons (car cdr)
- "Destructive: Sets CDR to the cons of CAR and CDR."
+ "Destructive: Set CDR to the cons of CAR and CDR."
`(setq ,cdr (cons ,car ,cdr)))
(defmacro !cdr (list)
- "Destructive: Sets LIST to the cdr of LIST."
+ "Destructive: Set LIST to the cdr of LIST."
`(setq ,list (cdr ,list)))
(defmacro --each (list &rest body)
@@ -66,7 +66,7 @@ special values."
(!cdr ,l)))))
(defun -each (list fn)
- "Calls FN with every item in LIST. Returns nil, used for side-effects only."
+ "Call FN with every item in LIST. Return nil, used for side-effects only."
(--each list (funcall fn it)))
(put '-each 'lisp-indent-function 1)
@@ -87,8 +87,8 @@ special values."
(!cdr ,l)))))
(defun -each-while (list pred fn)
- "Calls FN with every item in LIST while (PRED item) is non-nil.
-Returns nil, used for side-effects only."
+ "Call FN with every item in LIST while (PRED item) is non-nil.
+Return nil, used for side-effects only."
(--each-while list (funcall pred it) (funcall fn it)))
(put '-each-while 'lisp-indent-function 2)
@@ -111,7 +111,7 @@ Returns nil, used for side-effects only."
(put '-dotimes 'lisp-indent-function 1)
(defun -map (fn list)
- "Returns a new list consisting of the result of applying FN to the items in
LIST."
+ "Return a new list consisting of the result of applying FN to the items in
LIST."
(mapcar fn list))
(defmacro --map (form list)
@@ -127,9 +127,9 @@ Returns nil, used for side-effects only."
acc))
(defun -reduce-from (fn initial-value list)
- "Returns the result of applying FN to INITIAL-VALUE and the
+ "Return the result of applying FN to INITIAL-VALUE and the
first item in LIST, then applying FN to that result and the 2nd
-item, etc. If LIST contains no items, returns INITIAL-VALUE and
+item, etc. If LIST contains no items, return INITIAL-VALUE and
FN is not called.
In the anaphoric form `--reduce-from', the accumulated value is
@@ -146,10 +146,10 @@ exposed as `acc`."
(let (acc it) ,form)))))
(defun -reduce (fn list)
- "Returns the result of applying FN to the first 2 items in LIST,
+ "Return the result of applying FN to the first 2 items in LIST,
then applying FN to that result and the 3rd item, etc. If LIST
contains no items, FN must accept no arguments as well, and
-reduce returns the result of calling FN with no arguments. If
+reduce return the result of calling FN with no arguments. If
LIST has only 1 item, it is returned and FN is not called.
In the anaphoric form `--reduce', the accumulated value is
@@ -176,7 +176,7 @@ operation associates from right instead of from left."
(defun -reduce-r (fn list)
"Replace conses with FN and evaluate the resulting expression.
The final nil is ignored. If LIST contains no items, FN must
-accept no arguments as well, and reduce returns the result of
+accept no arguments as well, and reduce return the result of
calling FN with no arguments. If LIST has only 1 item, it is
returned and FN is not called.
@@ -204,7 +204,7 @@ associates from right instead of from left."
(nreverse ,r))))
(defun -filter (pred list)
- "Returns a new list of the items in LIST for which PRED returns a non-nil
value.
+ "Return a new list of the items in LIST for which PRED returns a non-nil
value.
Alias: `-select'"
(--filter (funcall pred it) list))
@@ -218,7 +218,7 @@ Alias: `-select'"
`(--filter (not ,form) ,list))
(defun -remove (pred list)
- "Returns a new list of the items in LIST for which PRED returns nil.
+ "Return a new list of the items in LIST for which PRED returns nil.
Alias: `-reject'"
(--remove (funcall pred it) list))
@@ -236,17 +236,9 @@ Alias: `-reject'"
(nreverse ,r))))
(defun -keep (fn list)
- "Returns a new list of the non-nil results of applying FN to the items in
LIST."
+ "Return a new list of the non-nil results of applying FN to the items in
LIST."
(--keep (funcall fn it) list))
-(defmacro --map-when (pred rep list)
- "Anaphoric form of `-map-when'."
- (declare (debug (form form form)))
- (let ((r (make-symbol "result")))
- `(let (,r)
- (--each ,list (!cons (if ,pred ,rep it) ,r))
- (nreverse ,r))))
-
(defmacro --map-indexed (form list)
"Anaphoric form of `-map-indexed'."
(declare (debug (form form)))
@@ -257,38 +249,56 @@ Alias: `-reject'"
(nreverse ,r))))
(defun -map-indexed (fn list)
- "Returns a new list consisting of the result of (FN index item) for each
item in LIST.
+ "Return a new list consisting of the result of (FN index item) for each item
in LIST.
In the anaphoric form `--map-indexed', the index is exposed as `it-index`."
(--map-indexed (funcall fn it-index it) list))
+(defmacro --map-when (pred rep list)
+ "Anaphoric form of `-map-when'."
+ (declare (debug (form form form)))
+ (let ((r (make-symbol "result")))
+ `(let (,r)
+ (--each ,list (!cons (if ,pred ,rep it) ,r))
+ (nreverse ,r))))
+
(defun -map-when (pred rep list)
- "Returns a new list where the elements in LIST that does not match the PRED
function
+ "Return a new list where the elements in LIST that does 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."
+through the REP function.
+
+Alias: `-replace-where'
+
+See also: `-update-at'"
(--map-when (funcall pred it) (funcall rep it) list))
-(defalias '--replace-where '--map-when)
(defalias '-replace-where '-map-when)
+(defalias '--replace-where '--map-when)
(defun -replace (old new list)
"Replace all OLD items in LIST with NEW.
-Elements are compared using `equal'."
+Elements are compared using `equal'.
+
+See also: `-replace-at'"
(--map-when (equal it old) new list))
(defun -flatten (l)
- "Takes a nested list L and returns its contents as a single, flat list."
+ "Take a nested list L and return its contents as a single, flat list.
+
+See also: `-flatten-n'"
(if (and (listp l) (listp (cdr l)))
(-mapcat '-flatten l)
(list l)))
(defun -flatten-n (num list)
- "Flatten NUM levels of a nested LIST."
+ "Flatten NUM levels of a nested LIST.
+
+See also: `-flatten'"
(-last-item (--iterate (--mapcat (-list it) it) list (1+ num))))
(defun -concat (&rest lists)
- "Returns a new list with the concatenation of the elements in the supplied
LISTS."
+ "Return a new list with the concatenation of the elements in the supplied
LISTS."
(apply 'append lists))
(defmacro --mapcat (form list)
@@ -297,7 +307,7 @@ Elements are compared using `equal'."
`(apply 'append (--map ,form ,list)))
(defun -mapcat (fn list)
- "Returns the concatenation of the result of mapping FN over LIST.
+ "Return the concatenation of the result of mapping FN over LIST.
Thus function FN should return a list."
(--mapcat (funcall fn it) list))
@@ -308,7 +318,9 @@ FUN takes the element matching PRED as input.
This function can be used as replacement for `,@' in case you
need to splice several lists at marked positions (for example
-with keywords)."
+with keywords).
+
+See also: `-splice-list', `-insert-at'"
(let (r)
(--each list
(if (funcall pred it)
@@ -324,7 +336,7 @@ with keywords)."
(defun -splice-list (pred new-list list)
"Splice NEW-LIST in place of elements matching PRED in LIST.
-See also more general version: `-splice'."
+See also: `-splice', `-insert-at'"
(-splice pred (lambda (_) new-list) list))
(defun --splice-list (pred new-list list)
@@ -332,7 +344,7 @@ See also more general version: `-splice'."
`(-splice-list (lambda (it) ,pred) ,new-list ,list))
(defun -cons* (&rest args)
- "Makes a new list from the elements of ARGS.
+ "Make a new list from the elements of ARGS.
The last 2 members of ARGS are used as the final cons of the
result so if the final member of ARGS is not a list the result is
@@ -357,11 +369,11 @@ If ELEMENTS is non nil, append these to the list as well."
,n)))
(defun -first (pred list)
- "Returns the first x in LIST where (PRED x) is non-nil, else nil.
+ "Return the first x in LIST where (PRED x) is non-nil, else nil.
To get the first item in the list no questions asked, use `car'.
-This function is also available as `-find'."
+Alias: `-find'"
(--first (funcall pred it) list))
(defalias '-find '-first)
@@ -381,10 +393,10 @@ This function is also available as `-find'."
(--last (funcall pred it) list))
(defalias '-first-item 'car
- "Returns the first item of LIST, or nil on an empty list.")
+ "Return the first item of LIST, or nil on an empty list.")
(defun -last-item (list)
- "Returns the last item of LIST, or nil on an empty list."
+ "Return the last item of LIST, or nil on an empty list."
(car (last list)))
(defmacro --count (pred list)
@@ -408,14 +420,13 @@ This function is also available as `-find'."
`(---truthy? (--first ,form ,list)))
(defun -any? (pred list)
- "Returns t if (PRED x) is non-nil for any x in LIST, else nil.
+ "Return t if (PRED x) is non-nil for any x in LIST, else nil.
-Alias: `-some?'"
+Alias: `-any-p', `-some?', `-some-p'"
(--any? (funcall pred it) list))
(defalias '-some? '-any?)
(defalias '--some? '--any?)
-
(defalias '-any-p '-any?)
(defalias '--any-p '--any?)
(defalias '-some-p '-any?)
@@ -430,14 +441,13 @@ Alias: `-some?'"
(---truthy? ,a))))
(defun -all? (pred list)
- "Returns t if (PRED x) is non-nil for all x in LIST, else nil.
+ "Return t if (PRED x) is non-nil for all x in LIST, else nil.
-Alias: `-every?'"
+Alias: `-all-p', `-every?', `-every-p'"
(--all? (funcall pred it) list))
(defalias '-every? '-all?)
(defalias '--every? '--all?)
-
(defalias '-all-p '-all?)
(defalias '--all-p '--all?)
(defalias '-every-p '-all?)
@@ -449,7 +459,9 @@ Alias: `-every?'"
`(--all? (not ,form) ,list))
(defun -none? (pred list)
- "Returns t if (PRED x) is nil for all x in LIST, else nil."
+ "Return t if (PRED x) is nil for all x in LIST, else nil.
+
+Alias: `-none-p'"
(--none? (funcall pred it) list))
(defalias '-none-p '-none?)
@@ -466,8 +478,10 @@ Alias: `-every?'"
(---truthy? (and ,y ,n)))))
(defun -only-some? (pred list)
- "Returns `t` if there is a mix of items in LIST that matches and does not
match PRED.
-Returns `nil` both if all items match the predicate, and if none of the items
match the predicate."
+ "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.
+
+Alias: `-only-some-p'"
(--only-some? (funcall pred it) list))
(defalias '-only-some-p '-only-some?)
@@ -500,7 +514,7 @@ section is returned. Defaults to 1."
(nreverse new-list)))
(defun -take (n list)
- "Returns a new list of the first N items in LIST, or all items if there are
fewer than N."
+ "Return a new list of the first N items in LIST, or all items if there are
fewer than N."
(let (result)
(--dotimes n
(when list
@@ -508,7 +522,7 @@ section is returned. Defaults to 1."
(!cdr list)))
(nreverse result)))
-(defalias '-drop 'nthcdr "Returns the tail of LIST without the first N items.")
+(defalias '-drop 'nthcdr "Return the tail of LIST without the first N items.")
(defmacro --take-while (form list)
"Anaphoric form of `-take-while'."
@@ -519,7 +533,7 @@ section is returned. Defaults to 1."
(nreverse ,r))))
(defun -take-while (pred list)
- "Returns a new list of successive items from LIST while (PRED item) returns
a non-nil value."
+ "Return a new list of successive items from LIST while (PRED item) returns a
non-nil value."
(--take-while (funcall pred it) list))
(defmacro --drop-while (form list)
@@ -532,11 +546,11 @@ section is returned. Defaults to 1."
,l)))
(defun -drop-while (pred list)
- "Returns the tail of LIST starting from the first item for which (PRED item)
returns nil."
+ "Return the tail of LIST starting from the first item for which (PRED item)
returns nil."
(--drop-while (funcall pred it) list))
(defun -split-at (n list)
- "Returns a list of ((-take N LIST) (-drop N LIST)), in no more than one pass
through the list."
+ "Return a list of ((-take N LIST) (-drop N LIST)), in no more than one pass
through the list."
(let (result)
(--dotimes n
(when list
@@ -552,17 +566,23 @@ The time complexity is O(n)."
(append (-drop (- n) list) (-take (- n) list))))
(defun -insert-at (n x list)
- "Returns a list with X inserted into LIST at position N."
+ "Return a list with X inserted into LIST at position N.
+
+See also: `-splice', `-splice-list'"
(let ((split-list (-split-at n list)))
(nconc (car split-list) (cons x (cadr split-list)))))
(defun -replace-at (n x list)
- "Return a list with element at Nth position in LIST replaced with X."
+ "Return a list with element at Nth position in LIST replaced with X.
+
+See also: `-replace'"
(let ((split-list (-split-at n list)))
(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))`."
+ "Return a list with element at Nth position in LIST replaced with `(func
(nth n list))`.
+
+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))))))
@@ -572,13 +592,17 @@ The time complexity is O(n)."
`(-update-at ,n (lambda (it) ,form) ,list))
(defun -remove-at (n list)
- "Return a list with element at Nth position in LIST removed."
+ "Return a list with element at Nth position in LIST removed.
+
+See also: `-remove-at-indices', `-remove'"
(-remove-at-indices (list n) list))
(defun -remove-at-indices (indices list)
"Return a list whose elements are elements from LIST without
elements selected as `(nth i list)` for all i
-from INDICES."
+from INDICES.
+
+See also: `-remove-at', `-remove'"
(let* ((indices (-sort '< indices))
(diffs (cons (car indices) (-map '1- (-zip-with '- (cdr indices)
indices))))
r)
@@ -607,7 +631,7 @@ from INDICES."
(list (nreverse ,r) ,l))))
(defun -split-with (pred list)
- "Returns a list of ((-take-while PRED LIST) (-drop-while PRED LIST)), in no
more than one pass through the list."
+ "Return a list of ((-take-while PRED LIST) (-drop-while PRED LIST)), in no
more than one pass through the list."
(--split-with (funcall pred it) list))
(defmacro -split-on (item list)
@@ -618,7 +642,7 @@ Empty lists are also removed from the result.
Comparison is done by `equal'.
-See also `-split-when'."
+See also `-split-when'"
(declare (debug (form form)))
`(-split-when (lambda (it) (equal it ,item)) ,list))
@@ -655,7 +679,7 @@ This function can be thought of as a generalization of
(list (nreverse ,y) (nreverse ,n)))))
(defun -separate (pred list)
- "Returns a list of ((-filter PRED LIST) (-remove PRED LIST)), in one pass
through the list."
+ "Return a list of ((-filter PRED LIST) (-remove PRED LIST)), in one pass
through the list."
(--separate (funcall pred it) list))
(defun ---partition-all-in-steps-reversed (n step list)
@@ -670,12 +694,12 @@ This function can be thought of as a generalization of
result))
(defun -partition-all-in-steps (n step list)
- "Returns a new list with the items in LIST grouped into N-sized sublists at
offsets STEP apart.
+ "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."
(nreverse (---partition-all-in-steps-reversed n step list)))
(defun -partition-in-steps (n step list)
- "Returns a new list with the items in LIST grouped into N-sized sublists at
offsets STEP apart.
+ "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."
(let ((result (---partition-all-in-steps-reversed n step list)))
@@ -684,12 +708,12 @@ those items are discarded."
(nreverse result)))
(defun -partition-all (n list)
- "Returns a new list with the items in LIST grouped into N-sized sublists.
+ "Return a new list with the items in LIST grouped into N-sized sublists.
The last group may contain less than N items."
(-partition-all-in-steps n n list))
(defun -partition (n list)
- "Returns a new list with the items in LIST grouped into N-sized sublists.
+ "Return a new list with the items in LIST grouped into N-sized sublists.
If there are not enough items to make the last group N-sized,
those items are discarded."
(-partition-in-steps n n list))
@@ -722,7 +746,7 @@ those items are discarded."
(nreverse ,r))))))
(defun -partition-by (fn list)
- "Applies FN to each item in LIST, splitting it each time FN returns a new
value."
+ "Apply FN to each item in LIST, splitting it each time FN returns a new
value."
(--partition-by (funcall fn it) list))
(defmacro --partition-by-header (form list)
@@ -757,8 +781,8 @@ those items are discarded."
(nreverse ,r))))))
(defun -partition-by-header (fn list)
- "Applies FN to the first item in LIST. That is the header
-value. Applies FN to each item in LIST, splitting it each time FN
+ "Apply FN to the first item in LIST. That is the header
+value. Apply FN to each item in LIST, splitting it each time FN
returns the header value, but only after seeing at least one
other value (the body)."
(--partition-by-header (funcall fn it) list))
@@ -797,7 +821,7 @@ elements of LIST. Keys are compared by `equal'."
(--group-by (funcall fn it) list))
(defun -interpose (sep list)
- "Returns a new list of all elements in LIST separated by SEP."
+ "Return a new list of all elements in LIST separated by SEP."
(let (result)
(when list
(!cons (car list) result)
@@ -808,7 +832,7 @@ elements of LIST. Keys are compared by `equal'."
(nreverse result)))
(defun -interleave (&rest lists)
- "Returns a new list of the first item in each list, then the second etc."
+ "Return a new list of the first item in each list, then the second etc."
(let (result)
(while (-none? 'null lists)
(--each lists (!cons (car it) result))
@@ -869,7 +893,7 @@ longest input list."
(apply '-zip (apply '-pad (cons fill-value lists))))
(defun -cycle (list)
- "Returns an infinite copy of LIST that will cycle through the
+ "Return an infinite copy of LIST that will cycle through the
elements and repeat from the beginning."
(let ((newlist (-map 'identity list)))
(nconc newlist newlist)))
@@ -882,7 +906,7 @@ will all have the same length."
(--map (append (cdr it) (-repeat (- n (car it)) fill-value)) annotations)))
(defun -annotate (fn list)
- "Returns a list of cons cells where each cell is FN applied to each
+ "Return a list of cons cells where each cell is FN applied to each
element of LIST paired with the unmodified element of LIST."
(-zip (-map fn list) list))
@@ -918,7 +942,7 @@ The outer product is computed by applying fn to all possible
combinations created by taking one element from each list in
order. The dimension of the result is (length lists).
-See also: `-table-flat'."
+See also: `-table-flat'"
(let ((restore-lists (copy-sequence lists))
(last-list (last lists))
(re (--map nil (number-sequence 1 (length lists)))))
@@ -944,7 +968,7 @@ of the result. This is equivalent to calling:
but the implementation here is much more efficient.
-See also: `-flatten-n', `-table'."
+See also: `-flatten-n', `-table'"
(let ((restore-lists (copy-sequence lists))
(last-list (last lists))
re)
@@ -955,8 +979,8 @@ See also: `-flatten-n', `-table'."
(nreverse re)))
(defun -partial (fn &rest args)
- "Takes a function FN and fewer than the normal arguments to FN,
-and returns a fn that takes a variable number of additional 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))
@@ -1013,9 +1037,9 @@ as `(nth i list)` for all i from INDICES."
(nreverse r)))
(defmacro -> (x &optional form &rest more)
- "Threads the expr through the forms. Inserts X as the second
-item in the first form, making a list of it if it is not a list
-already. If there are more forms, inserts the first form as the
+ "Thread the expr through the forms. Insert X as the second item
+in the first form, making a list of it if it is not a list
+already. If there are more forms, insert the first form as the
second item in second form, etc."
(cond
((null form) x)
@@ -1025,9 +1049,9 @@ second item in second form, etc."
(:else `(-> (-> ,x ,form) ,@more))))
(defmacro ->> (x form &rest more)
- "Threads the expr through the forms. Inserts X as the last item
+ "Thread the expr through the forms. Insert X as the last item
in the first form, making a list of it if it is not a list
-already. If there are more forms, inserts the first form as the
+already. If there are more forms, insert the first form as the
last item in second form, etc."
(if (null more)
(if (listp form)
@@ -1036,10 +1060,10 @@ last item in second form, etc."
`(->> (->> ,x ,form) ,@more)))
(defmacro --> (x form &rest more)
- "Threads the expr through the forms. Inserts X at the position
+ "Thread the expr through the forms. Insert X at the position
signified by the token `it' in the first form. If there are more
-forms, inserts the first form at the position signified by `it'
-in in second form, etc."
+forms, insert the first form at the position signified by `it' in
+in second form, etc."
(if (null more)
(if (listp form)
(--map-when (eq it 'it) x form)
@@ -1051,7 +1075,7 @@ in in second form, etc."
(put '--> 'lisp-indent-function 1)
(defun -grade-up (comparator list)
- "Grades elements of LIST using COMPARATOR relation, yielding a
+ "Grade elements of LIST using COMPARATOR relation, yielding a
permutation vector such that applying this permutation to LIST
sorts it in ascending order."
;; ugly hack to "fix" lack of lexical scope
@@ -1061,7 +1085,7 @@ sorts it in ascending order."
(-map 'cdr))))
(defun -grade-down (comparator list)
- "Grades elements of LIST using COMPARATOR relation, yielding a
+ "Grade elements of LIST using COMPARATOR relation, yielding a
permutation vector such that applying this permutation to LIST
sorts it in descending order."
;; ugly hack to "fix" lack of lexical scope
@@ -1145,6 +1169,8 @@ Alias: `-uniq'"
(--each list (unless (-contains? result it) (!cons it result)))
(nreverse result)))
+(defalias '-uniq '-distinct)
+
(defun -union (list list2)
"Return a new list containing the elements of LIST1 and elements of LIST2
that are not in LIST1.
The test for equality is done with `equal',
@@ -1154,8 +1180,6 @@ or with `-compare-fn' if that's non-nil."
(--each list2 (unless (-contains? result it) (!cons it result)))
(nreverse result)))
-(defalias '-uniq '-distinct)
-
(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',
@@ -1171,12 +1195,16 @@ or with `-compare-fn' if that's non-nil."
(defvar -compare-fn nil
"Tests for equality use this function or `equal' if this is nil.
It should only be set using dynamic scope with a let, like:
-(let ((-compare-fn =)) (-union numbers1 numbers2 numbers3)")
+
+ (let ((-compare-fn =)) (-union numbers1 numbers2 numbers3)")
(defun -contains? (list element)
- "Return whether LIST contains ELEMENT.
-The test for equality is done with `equal',
-or with `-compare-fn' if that's non-nil."
+ "Return non-nil if LIST contains ELEMENT.
+
+The test for equality is done with `equal', or with `-compare-fn'
+if that's non-nil.
+
+Alias: `-contains-p'"
(not
(null
(cond
@@ -1195,7 +1223,9 @@ or with `-compare-fn' if that's non-nil."
(defun -same-items? (list list2)
"Return true if LIST and LIST2 has the same items.
-The order of the elements in the lists does not matter."
+The order of the elements in the lists does not matter.
+
+Alias: `-same-items-p'"
(let ((length-a (length list))
(length-b (length list2)))
(and
@@ -1205,19 +1235,25 @@ The order of the elements in the lists does not matter."
(defalias '-same-items-p '-same-items?)
(defun -is-prefix? (prefix list)
- "Return non-nil if PREFIX is prefix of LIST."
+ "Return non-nil if PREFIX is prefix of LIST.
+
+Alias: `-is-prefix-p'"
(--each-while list (equal (car prefix) it)
(!cdr prefix))
(not prefix))
(defun -is-suffix? (suffix list)
- "Return non-nil if SUFFIX is suffix of LIST."
+ "Return non-nil if SUFFIX is suffix of LIST.
+
+Alias: `-is-suffix-p'"
(-is-prefix? (nreverse suffix) (nreverse list)))
(defun -is-infix? (infix list)
"Return non-nil if INFIX is infix of LIST.
-This operation runs in O(n^2) time"
+This operation runs in O(n^2) time
+
+Alias: `-is-infix-p'"
(let (done)
(while (and (not done) list)
(setq done (-is-prefix? infix list))
@@ -1230,7 +1266,7 @@ This operation runs in O(n^2) time"
(defun -sort (comparator list)
"Sort LIST, stably, comparing elements using COMPARATOR.
-Returns the sorted list. LIST is NOT modified by side effects.
+Return the sorted list. LIST is NOT modified by side effects.
COMPARATOR 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) comparator))
@@ -1250,7 +1286,7 @@ not, return a list with ARGS as elements."
(defun -repeat (n x)
"Return a list with X repeated N times.
-Returns nil if N is less than 1."
+Return nil if N is less than 1."
(let (ret)
(--dotimes n (!cons x ret))
ret))
diff --git a/dev/examples.el b/dev/examples.el
index 23697c2..edf627a 100644
--- a/dev/examples.el
+++ b/dev/examples.el
@@ -9,45 +9,33 @@
(defun square (num) (* num num))
(defun three-letters () '("A" "B" "C"))
-(def-example-group "List to list" nil
+(def-example-group "Maps"
+ "Functions in this category take a transforming function, which
+is then applied sequentially to each or selected elements of the
+input list. The results are collected in order and returned as
+new list."
+
(defexamples -map
(-map (lambda (num) (* num num)) '(1 2 3 4)) => '(1 4 9 16)
(-map 'square '(1 2 3 4)) => '(1 4 9 16)
(--map (* it it) '(1 2 3 4)) => '(1 4 9 16)
(--map (concat it it) (three-letters)) => '("AA" "BB" "CC"))
- (defexamples -filter
- (-filter (lambda (num) (= 0 (% num 2))) '(1 2 3 4)) => '(2 4)
- (-filter 'even? '(1 2 3 4)) => '(2 4)
- (--filter (= 0 (% it 2)) '(1 2 3 4)) => '(2 4))
-
- (defexamples -remove
- (-remove (lambda (num) (= 0 (% num 2))) '(1 2 3 4)) => '(1 3)
- (-remove 'even? '(1 2 3 4)) => '(1 3)
- (--remove (= 0 (% it 2)) '(1 2 3 4)) => '(1 3)
- (let ((mod 2)) (-remove (lambda (num) (= 0 (% num mod))) '(1 2 3 4))) =>
'(1 3)
- (let ((mod 2)) (--remove (= 0 (% it mod)) '(1 2 3 4))) => '(1 3))
-
- (defexamples -keep
- (-keep 'cdr '((1 2 3) (4 5) (6))) => '((2 3) (5))
- (-keep (lambda (num) (when (> num 3) (* 10 num))) '(1 2 3 4 5 6)) => '(40
50 60)
- (--keep (when (> it 3) (* 10 it)) '(1 2 3 4 5 6)) => '(40 50 60))
-
(defexamples -map-when
(-map-when 'even? 'square '(1 2 3 4)) => '(1 4 3 16)
(--map-when (> it 2) (* it it) '(1 2 3 4)) => '(1 2 9 16)
(--map-when (= it 2) 17 '(1 2 3 4)) => '(1 17 3 4)
(-map-when (lambda (n) (= n 3)) (lambda (n) 0) '(1 2 3 4)) => '(1 2 0 4))
- (defexamples -replace
- (-replace 1 "1" '(1 2 3 4 3 2 1)) => '("1" 2 3 4 3 2 "1")
- (-replace "foo" "bar" '("a" "nice" "foo" "sentence" "about" "foo")) =>
'("a" "nice" "bar" "sentence" "about" "bar")
- (-replace 1 2 nil) => nil)
-
(defexamples -map-indexed
(-map-indexed (lambda (index item) (- item index)) '(1 2 3 4)) => '(1 1 1
1)
(--map-indexed (- it it-index) '(1 2 3 4)) => '(1 1 1 1))
+ (defexamples -annotate
+ (-annotate '1+ '(1 2 3)) => '((2 . 1) (3 . 2) (4 . 3))
+ (-annotate 'length '(("h" "e" "l" "l" "o") ("hello" "world"))) => '((5 .
("h" "e" "l" "l" "o")) (2 . ("hello" "world")))
+ (--annotate (< 1 it) '(0 1 2 3)) => '((nil . 0) (nil . 1) (t . 2) (t . 3)))
+
(defexamples -splice
(-splice 'even? (lambda (x) (list x x)) '(1 2 3 4)) => '(1 2 2 3 4 4)
(--splice 't (list it it) '(1 2 3 4)) => '(1 1 2 2 3 3 4 4)
@@ -57,29 +45,25 @@
(-splice-list 'keywordp '(a b c) '(1 :foo 2)) => '(1 a b c 2)
(-splice-list 'keywordp nil '(1 :foo 2)) => '(1 2))
- (defexamples -flatten
- (-flatten '((1))) => '(1)
- (-flatten '((1 (2 3) (((4 (5))))))) => '(1 2 3 4 5)
- (-flatten '(1 2 (3 . 4))) => '(1 2 (3 . 4)))
-
- (defexamples -flatten-n
- (-flatten-n 1 '((1 2) ((3 4) ((5 6))))) => '(1 2 (3 4) ((5 6)))
- (-flatten-n 2 '((1 2) ((3 4) ((5 6))))) => '(1 2 3 4 (5 6))
- (-flatten-n 3 '((1 2) ((3 4) ((5 6))))) => '(1 2 3 4 5 6)
- (-flatten-n 0 '(3 4)) => '(3 4)
- (-flatten-n 0 '((1 2) (3 4))) => '((1 2) (3 4))
- (-flatten-n 0 '(((1 2) (3 4)))) => '(((1 2) (3 4))))
-
- (defexamples -concat
- (-concat '(1)) => '(1)
- (-concat '(1) '(2)) => '(1 2)
- (-concat '(1) '(2 3) '(4)) => '(1 2 3 4)
- (-concat) => nil)
-
(defexamples -mapcat
(-mapcat 'list '(1 2 3)) => '(1 2 3)
(-mapcat (lambda (item) (list 0 item)) '(1 2 3)) => '(0 1 0 2 0 3)
- (--mapcat (list 0 it) '(1 2 3)) => '(0 1 0 2 0 3))
+ (--mapcat (list 0 it) '(1 2 3)) => '(0 1 0 2 0 3)))
+
+(def-example-group "Sublist selection"
+ "Functions returning a sublist of the original list."
+
+ (defexamples -filter
+ (-filter (lambda (num) (= 0 (% num 2))) '(1 2 3 4)) => '(2 4)
+ (-filter 'even? '(1 2 3 4)) => '(2 4)
+ (--filter (= 0 (% it 2)) '(1 2 3 4)) => '(2 4))
+
+ (defexamples -remove
+ (-remove (lambda (num) (= 0 (% num 2))) '(1 2 3 4)) => '(1 3)
+ (-remove 'even? '(1 2 3 4)) => '(1 3)
+ (--remove (= 0 (% it 2)) '(1 2 3 4)) => '(1 3)
+ (let ((mod 2)) (-remove (lambda (num) (= 0 (% num mod))) '(1 2 3 4))) =>
'(1 3)
+ (let ((mod 2)) (--remove (= 0 (% it mod)) '(1 2 3 4))) => '(1 3))
(defexamples -slice
(-slice '(1 2 3 4 5) 1) => '(2 3 4 5)
@@ -116,9 +100,42 @@
(-drop-while 'even? '(2 4 5 6)) => '(5 6)
(--drop-while (< it 4) '(1 2 3 4 3 2 1)) => '(4 3 2 1))
- (defexamples -rotate
- (-rotate 3 '(1 2 3 4 5 6 7)) => '(5 6 7 1 2 3 4)
- (-rotate -3 '(1 2 3 4 5 6 7)) => '(4 5 6 7 1 2 3))
+ (defexamples -select-by-indices
+ (-select-by-indices '(4 10 2 3 6) '("v" "e" "l" "o" "c" "i" "r" "a" "p"
"t" "o" "r")) => '("c" "o" "l" "o" "r")
+ (-select-by-indices '(2 1 0) '("a" "b" "c")) => '("c" "b" "a")
+ (-select-by-indices '(0 1 2 0 1 3 3 1) '("f" "a" "r" "l")) => '("f" "a"
"r" "f" "a" "l" "l" "a")))
+
+(def-example-group "List to list"
+ "Bag of various functions which modify input list."
+
+ (defexamples -keep
+ (-keep 'cdr '((1 2 3) (4 5) (6))) => '((2 3) (5))
+ (-keep (lambda (num) (when (> num 3) (* 10 num))) '(1 2 3 4 5 6)) => '(40
50 60)
+ (--keep (when (> it 3) (* 10 it)) '(1 2 3 4 5 6)) => '(40 50 60))
+
+ (defexamples -concat
+ (-concat '(1)) => '(1)
+ (-concat '(1) '(2)) => '(1 2)
+ (-concat '(1) '(2 3) '(4)) => '(1 2 3 4)
+ (-concat) => nil)
+
+ (defexamples -flatten
+ (-flatten '((1))) => '(1)
+ (-flatten '((1 (2 3) (((4 (5))))))) => '(1 2 3 4 5)
+ (-flatten '(1 2 (3 . 4))) => '(1 2 (3 . 4)))
+
+ (defexamples -flatten-n
+ (-flatten-n 1 '((1 2) ((3 4) ((5 6))))) => '(1 2 (3 4) ((5 6)))
+ (-flatten-n 2 '((1 2) ((3 4) ((5 6))))) => '(1 2 3 4 (5 6))
+ (-flatten-n 3 '((1 2) ((3 4) ((5 6))))) => '(1 2 3 4 5 6)
+ (-flatten-n 0 '(3 4)) => '(3 4)
+ (-flatten-n 0 '((1 2) (3 4))) => '((1 2) (3 4))
+ (-flatten-n 0 '(((1 2) (3 4)))) => '(((1 2) (3 4))))
+
+ (defexamples -replace
+ (-replace 1 "1" '(1 2 3 4 3 2 1)) => '("1" 2 3 4 3 2 "1")
+ (-replace "foo" "bar" '("a" "nice" "foo" "sentence" "about" "foo")) =>
'("a" "nice" "bar" "sentence" "about" "bar")
+ (-replace 1 2 nil) => nil)
(defexamples -insert-at
(-insert-at 1 'x '(a b c)) => '(a x b c)
@@ -166,7 +183,9 @@
(-remove-at-indices '(0) '(((a b) (c d) (e f g) h i ((j) k) l (m)))) => nil
(-remove-at-indices '(2 3) '((0) (1) (2) (3) (4) (5) (6))) => '((0) (1)
(4) (5) (6))))
-(def-example-group "Reductions" nil
+(def-example-group "Reductions"
+ "Functions reducing lists into single value."
+
(defexamples -reduce-from
(-reduce-from '- 10 '(1 2 3)) => 4
(-reduce-from (lambda (memo item)
@@ -301,7 +320,9 @@
(-is-infix? '(2 3 4) '(1 2 4 5)) => nil
(-is-infix? '(2 4) '(1 2 3 4 5)) => nil))
-(def-example-group "Partitioning" nil
+(def-example-group "Partitioning"
+ "Functions partitioning the input list into a list of lists."
+
(defexamples -split-at
(-split-at 3 '(1 2 3 4 5)) => '((1 2 3) (4 5))
(-split-at 17 '(1 2 3 4 5)) => '((1 2 3 4 5) nil))
@@ -372,7 +393,9 @@
(-group-by 'even? '(1 1 2 2 2 3 4 6 8)) => '((nil . (1 1 3)) (t . (2 2 2 4
6 8)))
(--group-by (car (split-string it "/")) '("a/b" "c/d" "a/e")) => '(("a" .
("a/b" "a/e")) ("c" . ("c/d")))))
-(def-example-group "Indexing" nil
+(def-example-group "Indexing"
+ "Return indices of elements based on predicates, sort elements by indices
etc."
+
(defexamples -elem-index
(-elem-index 2 '(6 7 8 2 3 4)) => 3
(-elem-index "bar" '("foo" "bar" "baz")) => 1
@@ -398,11 +421,6 @@
(--find-indices (< 5 it) '(2 4 1 6 3 3 5 8)) => '(3 7)
(-find-indices (-partial 'string-lessp "baz") '("bar" "foo" "baz")) =>
'(1))
- (defexamples -select-by-indices
- (-select-by-indices '(4 10 2 3 6) '("v" "e" "l" "o" "c" "i" "r" "a" "p"
"t" "o" "r")) => '("c" "o" "l" "o" "r")
- (-select-by-indices '(2 1 0) '("a" "b" "c")) => '("c" "b" "a")
- (-select-by-indices '(0 1 2 0 1 3 3 1) '("f" "a" "r" "l")) => '("f" "a"
"r" "f" "a" "l" "l" "a"))
-
(defexamples -grade-up
(-grade-up '< '(3 1 4 2 1 3 3)) => '(1 4 3 0 5 6 2)
(let ((l '(3 1 4 2 1 3 3))) (-select-by-indices (-grade-up '< l) l)) =>
'(1 1 2 3 3 3 4))
@@ -411,7 +429,9 @@
(-grade-down '< '(3 1 4 2 1 3 3)) => '(2 0 5 6 3 1 4)
(let ((l '(3 1 4 2 1 3 3))) (-select-by-indices (-grade-down '< l) l)) =>
'(4 3 3 3 2 1 1)))
-(def-example-group "Set operations" nil
+(def-example-group "Set operations"
+ "Operations pretending lists are sets."
+
(defexamples -union
(-union '(1 2 3) '(3 4 5)) => '(1 2 3 4 5)
(-union '(1 2 3 4) '()) => '(1 2 3 4)
@@ -431,7 +451,13 @@
(-distinct '()) => '()
(-distinct '(1 2 2 4)) => '(1 2 4)))
-(def-example-group "Other list operations" nil
+(def-example-group "Other list operations"
+ "Other list functions not fit to be classified elsewhere."
+
+ (defexamples -rotate
+ (-rotate 3 '(1 2 3 4 5 6 7)) => '(5 6 7 1 2 3 4)
+ (-rotate -3 '(1 2 3 4 5 6 7)) => '(4 5 6 7 1 2 3))
+
(defexamples -repeat
(-repeat 3 :a) => '(:a :a :a)
(-repeat 1 :a) => '(:a)
@@ -490,11 +516,6 @@
(-pad nil '(1 2 3) '(4 5) '(6 7 8 9 10)) => '((1 2 3 nil nil) (4 5 nil nil
nil) (6 7 8 9 10))
(-pad 0 '(1 2) '(3 4)) => '((1 2) (3 4)))
- (defexamples -annotate
- (-annotate '1+ '(1 2 3)) => '((2 . 1) (3 . 2) (4 . 3))
- (-annotate 'length '(("h" "e" "l" "l" "o") ("hello" "world"))) => '((5 .
("h" "e" "l" "l" "o")) (2 . ("hello" "world")))
- (--annotate (< 1 it) '(0 1 2 3)) => '((nil . 0) (nil . 1) (t . 2) (t . 3)))
-
(defexamples -table
(-table '* '(1 2 3) '(1 2 3)) => '((1 2 3) (2 4 6) (3 6 9))
(-table (lambda (a b) (-sum (-zip-with '* a b))) '((1 2) (3 4)) '((1 3) (2
4))) => '((7 15) (10 22))
@@ -540,7 +561,9 @@
(-list '(1 2 3) => '(1 2 3))
(-list '((1) (2)) => '((1) (2)))))
-(def-example-group "Tree operations" nil
+(def-example-group "Tree operations"
+ "Functions pretending lists are trees."
+
(defexamples -tree-map
(-tree-map '1+ '(1 (2 3) (4 (5 6) 7))) => '(2 (3 4) (5 (6 7) 8))
(-tree-map '(lambda (x) (cons x (expt 2 x))) '(1 (2 3) 4)) => '((1 . 2)
((2 . 4) (3 . 8)) (4 . 16))
@@ -615,7 +638,9 @@
(--> "def" (concat "abc" it "ghi") (upcase it)) => "ABCDEFGHI"
(--> "def" (concat "abc" it "ghi") upcase) => "ABCDEFGHI"))
-(def-example-group "Binding" nil
+(def-example-group "Binding"
+ "Convenient versions of `let` and `let*` constructs combined with flow
control."
+
(defexamples -when-let
(-when-let (match-index (string-match "d" "abcd")) (+ match-index 2)) => 5
(--when-let (member :b '(:a :b :c)) (cons :d it)) => '(:d :b :c)
@@ -633,7 +658,9 @@
(-if-let* ((x 5) (y 3) (z 7)) (+ x y z) "foo") => 15
(-if-let* ((x 5) (y nil) (z 7)) (+ x y z) "foo") => "foo"))
-(def-example-group "Side-effects" nil
+(def-example-group "Side-effects"
+ "Functions iterating over lists for side-effect only."
+
(defexamples -each
(let (s) (-each '(1 2 3) (lambda (item) (setq s (cons item s))))) => nil
(let (s) (-each '(1 2 3) (lambda (item) (setq s (cons item s)))) s) => '(3
2 1)
@@ -657,7 +684,9 @@
(let ((l '(3))) (!cdr l) l) => '()
(let ((l '(3 5))) (!cdr l) l) => '(5)))
-(def-example-group "Function combinators" "These combinators require Emacs 24
for its lexical scope. So they are offered in a separate package:
`dash-functional`."
+(def-example-group "Function combinators"
+ "These combinators require Emacs 24 for its lexical scope. So they are
offered in a separate package: `dash-functional`."
+
(defexamples -partial
(funcall (-partial '- 5) 3) => 2
(funcall (-partial '+ 5 2) 3) => 10)
- [elpa] externals/dash f18a520 326/439: Release 2.7.0, (continued)
- [elpa] externals/dash f18a520 326/439: Release 2.7.0, Phillip Lord, 2015/08/04
- [elpa] externals/dash f257fb9 328/439: Add -butlast, Phillip Lord, 2015/08/04
- [elpa] externals/dash d9879e9 329/439: Release 2.8.0, Phillip Lord, 2015/08/04
- [elpa] externals/dash 25c114c 330/439: Implementing a shallow copy counterpart to -clone., Phillip Lord, 2015/08/04
- [elpa] externals/dash 6fc652d 331/439: Merge pull request #95 from Wilfred/shallow-copy-function, Phillip Lord, 2015/08/04
- [elpa] externals/dash d37947a 332/439: Add -tree-seq, Phillip Lord, 2015/08/04
- [elpa] externals/dash 166bccd 333/439: Add -tree-map-nodes, Phillip Lord, 2015/08/04
- [elpa] externals/dash 3adad97 334/439: Add -non-nil, Phillip Lord, 2015/08/04
- [elpa] externals/dash ab99be6 335/439: Add -fix, Phillip Lord, 2015/08/04
- [elpa] externals/dash 2626840 336/439: Add -fixfn, Phillip Lord, 2015/08/04
- [elpa] externals/dash c6b92ae 324/439: Reorder the examples into more meaningful blocks,
Phillip Lord <=
- [elpa] externals/dash b1e585d 337/439: Update copyright notice, Phillip Lord, 2015/08/04
- [elpa] externals/dash f0831d3 339/439: Add -lambda, Phillip Lord, 2015/08/04
- [elpa] externals/dash 8f9fc41 340/439: Add support for multiple input arguments to -lambda, Phillip Lord, 2015/08/04
- [elpa] externals/dash 05fa92f 342/439: [-let] Transpose nreverse/flatten, Phillip Lord, 2015/08/04
- [elpa] externals/dash 7f2b3c7 343/439: [-lambda] test all match-forms before converting to regular lambda, Phillip Lord, 2015/08/04
- [elpa] externals/dash 947ffda 341/439: Add support for &rest match for non-list sequences (like . for improper lists), Phillip Lord, 2015/08/04
- [elpa] externals/dash a4be872 338/439: Add `-let` and `-let*`, Phillip Lord, 2015/08/04
- [elpa] externals/dash 9065e1b 344/439: [-let] Final cdr shift optimization, Phillip Lord, 2015/08/04
- [elpa] externals/dash 6f81492 346/439: [-lambda] Better error-handling, Phillip Lord, 2015/08/04
- [elpa] externals/dash 65a3736 349/439: [-let] Fix improper list non-symbol last argument handler, Phillip Lord, 2015/08/04