branch: externals/dash
commit 1b9061c5f506d657e157f046752e27ca3552ab78
Author: Matus Goljer <matus.gol...@gmail.com>
Commit: Matus Goljer <matus.gol...@gmail.com>
Update docs
---
README.md | 88 +++++++++++++++++++++++++++++++++++------
dash.texi | 132 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--------
2 files changed, 192 insertions(+), 28 deletions(-)
diff --git a/README.md b/README.md
index c24960d..95c6f7b 100644
--- a/README.md
+++ b/README.md
@@ -135,6 +135,10 @@ Functions reducing lists into single value.
* [-reduce-r-from](#-reduce-r-from-fn-initial-value-list) `(fn initial-value
list)`
* [-reduce](#-reduce-fn-list) `(fn list)`
* [-reduce-r](#-reduce-r-fn-list) `(fn list)`
+* [-reductions-from](#-reductions-from-fn-init-list) `(fn init list)`
+* [-reductions-r-from](#-reductions-r-from-fn-init-list) `(fn init list)`
+* [-reductions](#-reductions-fn-list) `(fn list)`
+* [-reductions-r](#-reductions-r-fn-list) `(fn list)`
* [-count](#-count-pred-list) `(pred list)`
* [-sum](#-sum-list) `(list)`
* [-running-sum](#-running-sum-list) `(list)`
@@ -910,6 +914,62 @@ See also:
[`-reduce-r-from`](#-reduce-r-from-fn-initial-value-list), [`-reduce`]
(--reduce-r (format "%s-%s" acc it) '(1 2 3)) ;; => "3-2-1"
```
+#### -reductions-from `(fn init list)`
+
+Return a list of the intermediate values of the reduction.
+
+See [`-reduce-from`](#-reduce-from-fn-initial-value-list) for explanation of
the arguments.
+
+See also: [`-reductions`](#-reductions-fn-list),
[`-reductions-r`](#-reductions-r-fn-list), [`-reduce-r`](#-reduce-r-fn-list)
+
+```el
+(-reductions-from (lambda (a i) (format "(%s FN %s)" a i)) "INIT" '(1 2 3 4))
;; => '("INIT" "(INIT FN 1)" "((INIT FN 1) FN 2)" "(((INIT FN 1) FN 2) FN 3)"
"((((INIT FN 1) FN 2) FN 3) FN 4)")
+(-reductions-from 'max 0 '(2 1 4 3)) ;; => '(0 2 2 4 4)
+(-reductions-from '* 1 '(1 2 3 4)) ;; => '(1 1 2 6 24)
+```
+
+#### -reductions-r-from `(fn init list)`
+
+Return a list of the intermediate values of the reduction.
+
+See [`-reduce-r-from`](#-reduce-r-from-fn-initial-value-list) for explanation
of the arguments.
+
+See also: [`-reductions-r`](#-reductions-r-fn-list),
[`-reductions`](#-reductions-fn-list), [`-reduce`](#-reduce-fn-list)
+
+```el
+(-reductions-r-from (lambda (i a) (format "(%s FN %s)" i a)) "INIT" '(1 2 3
4)) ;; => '("(1 FN (2 FN (3 FN (4 FN INIT))))" "(2 FN (3 FN (4 FN INIT)))" "(3
FN (4 FN INIT))" "(4 FN INIT)" "INIT")
+(-reductions-r-from 'max 0 '(2 1 4 3)) ;; => '(4 4 4 3 0)
+(-reductions-r-from '* 1 '(1 2 3 4)) ;; => '(24 24 12 4 1)
+```
+
+#### -reductions `(fn list)`
+
+Return a list of the intermediate values of the reduction.
+
+See [`-reduce`](#-reduce-fn-list) for explanation of the arguments.
+
+See also: [`-reductions-from`](#-reductions-from-fn-init-list),
[`-reductions-r`](#-reductions-r-fn-list), [`-reduce-r`](#-reduce-r-fn-list)
+
+```el
+(-reductions (lambda (a i) (format "(%s FN %s)" a i)) '(1 2 3 4)) ;; => '(1
"(1 FN 2)" "((1 FN 2) FN 3)" "(((1 FN 2) FN 3) FN 4)")
+(-reductions '+ '(1 2 3 4)) ;; => '(1 3 6 10)
+(-reductions '* '(1 2 3 4)) ;; => '(1 2 6 24)
+```
+
+#### -reductions-r `(fn list)`
+
+Return a list of the intermediate values of the reduction.
+
+See [`-reduce-r`](#-reduce-r-fn-list) for explanation of the arguments.
+
+See also: [`-reductions-r-from`](#-reductions-r-from-fn-init-list),
[`-reductions`](#-reductions-fn-list), [`-reduce`](#-reduce-fn-list)
+
+```el
+(-reductions-r (lambda (i a) (format "(%s FN %s)" i a)) '(1 2 3 4)) ;; =>
'("(1 FN (2 FN (3 FN 4)))" "(2 FN (3 FN 4))" "(3 FN 4)" 4)
+(-reductions-r '+ '(1 2 3 4)) ;; => '(10 9 7 4)
+(-reductions-r '* '(1 2 3 4)) ;; => '(24 24 12 4)
+```
+
#### -count `(pred list)`
Counts the number of items in `list` where (`pred` item) is non-nil.
@@ -933,10 +993,12 @@ Return the sum of `list`.
Return a list with running sums of items in `list`.
+`list` must be non-empty.
+
```el
-(-running-sum '()) ;; => nil
-(-running-sum '(1)) ;; => '(1)
(-running-sum '(1 2 3 4)) ;; => '(1 3 6 10)
+(-running-sum '(1)) ;; => '(1)
+(-running-sum '()) ;; Error
```
#### -product `(list)`
@@ -953,10 +1015,12 @@ Return the product of `list`.
Return a list with running products of items in `list`.
+`list` must be non-empty.
+
```el
-(-running-product '()) ;; => nil
-(-running-product '(1)) ;; => '(1)
(-running-product '(1 2 3 4)) ;; => '(1 2 6 24)
+(-running-product '(1)) ;; => '(1)
+(-running-product '()) ;; Error
```
#### -min `(list)`
@@ -1507,22 +1571,22 @@ Return the permutations of `list`.
#### -inits `(list)`
-Return all non-empty prefixes of `list`.
+Return all prefixes of `list`.
```el
-(-inits '(1 2 3 4)) ;; => '((1) (1 2) (1 2 3) (1 2 3 4))
-(-inits nil) ;; => nil
-(-inits '(1)) ;; => '((1))
+(-inits '(1 2 3 4)) ;; => '(nil (1) (1 2) (1 2 3) (1 2 3 4))
+(-inits nil) ;; => '(nil)
+(-inits '(1)) ;; => '(nil (1))
```
#### -tails `(list)`
-Return all non-empty suffixes of `list`
+Return all suffixes of `list`
```el
-(-tails '(1 2 3 4)) ;; => '((1 2 3 4) (2 3 4) (3 4) (4))
-(-tails nil) ;; => nil
-(-tails '(1)) ;; => '((1))
+(-tails '(1 2 3 4)) ;; => '((1 2 3 4) (2 3 4) (3 4) (4) nil)
+(-tails nil) ;; => '(nil)
+(-tails '(1)) ;; => '((1) nil)
```
#### -distinct `(list)`
diff --git a/dash.texi b/dash.texi
index ece320c..e0737a7 100644
--- a/dash.texi
+++ b/dash.texi
@@ -1180,6 +1180,102 @@ See also: @code{-reduce-r-from}
(@pxref{-reduce-r-from}), @code{-reduce} (@pxref
@end example
@end defun
+@anchor{-reductions-from}
+@defun -reductions-from (fn init list)
+Return a list of the intermediate values of the reduction.
+
+See @code{-reduce-from} (@pxref{-reduce-from}) for explanation of the
arguments.
+
+See also: @code{-reductions} (@pxref{-reductions}), @code{-reductions-r}
(@pxref{-reductions-r}), @code{-reduce-r} (@pxref{-reduce-r})
+
+@example
+@group
+(-reductions-from (lambda (a i) (format "(%s FN %s)" a i)) "INIT" '(1 2 3 4))
+ @result{} '("INIT" "(INIT FN 1)" "((INIT FN 1) FN 2)" "(((INIT FN 1) FN 2)
FN 3)" "((((INIT FN 1) FN 2) FN 3) FN 4)")
+@end group
+@group
+(-reductions-from 'max 0 '(2 1 4 3))
+ @result{} '(0 2 2 4 4)
+@end group
+@group
+(-reductions-from '* 1 '(1 2 3 4))
+ @result{} '(1 1 2 6 24)
+@end group
+@end example
+@end defun
+
+@anchor{-reductions-r-from}
+@defun -reductions-r-from (fn init list)
+Return a list of the intermediate values of the reduction.
+
+See @code{-reduce-r-from} (@pxref{-reduce-r-from}) for explanation of the
arguments.
+
+See also: @code{-reductions-r} (@pxref{-reductions-r}), @code{-reductions}
(@pxref{-reductions}), @code{-reduce} (@pxref{-reduce})
+
+@example
+@group
+(-reductions-r-from (lambda (i a) (format "(%s FN %s)" i a)) "INIT" '(1 2 3 4))
+ @result{} '("(1 FN (2 FN (3 FN (4 FN INIT))))" "(2 FN (3 FN (4 FN INIT)))"
"(3 FN (4 FN INIT))" "(4 FN INIT)" "INIT")
+@end group
+@group
+(-reductions-r-from 'max 0 '(2 1 4 3))
+ @result{} '(4 4 4 3 0)
+@end group
+@group
+(-reductions-r-from '* 1 '(1 2 3 4))
+ @result{} '(24 24 12 4 1)
+@end group
+@end example
+@end defun
+
+@anchor{-reductions}
+@defun -reductions (fn list)
+Return a list of the intermediate values of the reduction.
+
+See @code{-reduce} (@pxref{-reduce}) for explanation of the arguments.
+
+See also: @code{-reductions-from} (@pxref{-reductions-from}),
@code{-reductions-r} (@pxref{-reductions-r}), @code{-reduce-r}
(@pxref{-reduce-r})
+
+@example
+@group
+(-reductions (lambda (a i) (format "(%s FN %s)" a i)) '(1 2 3 4))
+ @result{} '(1 "(1 FN 2)" "((1 FN 2) FN 3)" "(((1 FN 2) FN 3) FN 4)")
+@end group
+@group
+(-reductions '+ '(1 2 3 4))
+ @result{} '(1 3 6 10)
+@end group
+@group
+(-reductions '* '(1 2 3 4))
+ @result{} '(1 2 6 24)
+@end group
+@end example
+@end defun
+
+@anchor{-reductions-r}
+@defun -reductions-r (fn list)
+Return a list of the intermediate values of the reduction.
+
+See @code{-reduce-r} (@pxref{-reduce-r}) for explanation of the arguments.
+
+See also: @code{-reductions-r-from} (@pxref{-reductions-r-from}),
@code{-reductions} (@pxref{-reductions}), @code{-reduce} (@pxref{-reduce})
+
+@example
+@group
+(-reductions-r (lambda (i a) (format "(%s FN %s)" i a)) '(1 2 3 4))
+ @result{} '("(1 FN (2 FN (3 FN 4)))" "(2 FN (3 FN 4))" "(3 FN 4)" 4)
+@end group
+@group
+(-reductions-r '+ '(1 2 3 4))
+ @result{} '(10 9 7 4)
+@end group
+@group
+(-reductions-r '* '(1 2 3 4))
+ @result{} '(24 24 12 4)
+@end group
+@end example
+@end defun
+
@anchor{-count}
@defun -count (pred list)
Counts the number of items in @var{list} where (@var{pred} item) is non-nil.
@@ -1220,18 +1316,20 @@ Return the sum of @var{list}.
@defun -running-sum (list)
Return a list with running sums of items in @var{list}.
+@var{list} must be non-empty.
+
@example
@group
-(-running-sum '())
- @result{} nil
+(-running-sum '(1 2 3 4))
+ @result{} '(1 3 6 10)
@end group
@group
(-running-sum '(1))
@result{} '(1)
@end group
@group
-(-running-sum '(1 2 3 4))
- @result{} '(1 3 6 10)
+(-running-sum '())
+ @result{} error
@end group
@end example
@end defun
@@ -1260,18 +1358,20 @@ Return the product of @var{list}.
@defun -running-product (list)
Return a list with running products of items in @var{list}.
+@var{list} must be non-empty.
+
@example
@group
-(-running-product '())
- @result{} nil
+(-running-product '(1 2 3 4))
+ @result{} '(1 2 6 24)
@end group
@group
(-running-product '(1))
@result{} '(1)
@end group
@group
-(-running-product '(1 2 3 4))
- @result{} '(1 2 6 24)
+(-running-product '())
+ @result{} error
@end group
@end example
@end defun
@@ -2251,40 +2351,40 @@ Return the permutations of @var{list}.
@anchor{-inits}
@defun -inits (list)
-Return all non-empty prefixes of @var{list}.
+Return all prefixes of @var{list}.
@example
@group
(-inits '(1 2 3 4))
- @result{} '((1) (1 2) (1 2 3) (1 2 3 4))
+ @result{} '(nil (1) (1 2) (1 2 3) (1 2 3 4))
@end group
@group
(-inits nil)
- @result{} nil
+ @result{} '(nil)
@end group
@group
(-inits '(1))
- @result{} '((1))
+ @result{} '(nil (1))
@end group
@end example
@end defun
@anchor{-tails}
@defun -tails (list)
-Return all non-empty suffixes of @var{list}
+Return all suffixes of @var{list}
@example
@group
(-tails '(1 2 3 4))
- @result{} '((1 2 3 4) (2 3 4) (3 4) (4))
+ @result{} '((1 2 3 4) (2 3 4) (3 4) (4) nil)
@end group
@group
(-tails nil)
- @result{} nil
+ @result{} '(nil)
@end group
@group
(-tails '(1))
- @result{} '((1))
+ @result{} '((1) nil)
@end group
@end example
@end defun
