Add copyright assignment statement to documentation

9 years ago · 05dc0aa3fe
parent 1e14307e2d
commit 05dc0aa3fe
4 changed files with 702 additions and 534 deletions
--- a/README.md
+++ b/README.md
@ -202,6 +202,8 @@ Operations pretending lists are sets.
 * [-union](#-union-list-list2) `(list list2)`
 * [-difference](#-difference-list-list2) `(list list2)`
 * [-intersection](#-intersection-list-list2) `(list list2)`
+* [-powerset](#-powerset-list) `(list)`
+* [-permutations](#-permutations-list) `(list)`
 * [-distinct](#-distinct-list) `(list)`

 ### Other list operations
@ -251,7 +253,8 @@ Functions pretending lists are trees.

 * [->](#--x-optional-form-rest-more) `(x &optional form &rest more)`
 * [->>](#--x-optional-form-rest-more) `(x &optional form &rest more)`
-* [-->](#---x-form-rest-more) `(x form &rest more)`
+* [-->](#---x-rest-forms) `(x &rest forms)`
+* [-as->](#-as--value-variable-rest-forms) `(value variable &rest forms)`
 * [-some->](#-some--x-optional-form-rest-more) `(x &optional form &rest more)`
 * [-some->>](#-some--x-optional-form-rest-more) `(x &optional form &rest more)`
 * [-some-->](#-some---x-optional-form-rest-more) `(x &optional form &rest more)`
@ -1409,6 +1412,25 @@ or with `-compare-fn` if that's non-nil.
 (-intersection '(1 2 3 4) '(3 4 5 6)) ;; => '(3 4)
 ```

+#### -powerset `(list)`
+
+Return the power set of `list`.
+
+```el
+(-powerset '()) ;; => '(nil)
+(-powerset '(x y z)) ;; => '((x y z) (x y) (x z) (x) (y z) (y) (z) nil)
+```
+
+#### -permutations `(list)`
+
+Return the permutations of `list`.
+
+```el
+(-permutations '()) ;; => '(nil)
+(-permutations '(1 2)) ;; => '((1 2) (2 1))
+(-permutations '(a b c)) ;; => '((a b c) (a c b) (b a c) (b c a) (c a b) (c b a))
+```
+
 #### -distinct `(list)`

 Return a new list with all duplicates removed.
@ -1669,6 +1691,7 @@ Return the first item of `list`, or nil on an empty list.
 ```el
 (-first-item '(1 2 3)) ;; => 1
 (-first-item nil) ;; => nil
+(let ((list (list 1 2 3))) (setf (-first-item list) 5) list) ;; => '(5 2 3)
 ```

 #### -last-item `(list)`
@ -1678,6 +1701,7 @@ Return the last item of `list`, or nil on an empty list.
 ```el
 (-last-item '(1 2 3)) ;; => 3
 (-last-item nil) ;; => nil
+(let ((list (list 1 2 3))) (setf (-last-item list) 5) list) ;; => '(1 2 5)
 ```

 #### -butlast `(list)`
@ -1883,12 +1907,13 @@ last item in second form, etc.
 (->> '(1 2 3) (-map 'square) (-reduce '+)) ;; => 14
 ```

-#### --> `(x form &rest more)`
+#### --> `(x &rest forms)`
+
+Starting with the value of `x`, thread each expression through `forms`.

-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, insert the first form at the position signified by `it` in
-in second form, etc.
+Insert `x` at the position signified by the token `it` in the first
+form.  If there are more forms, insert the first form at the position
+signified by `it` in in second form, etc.

 ```el
 (--> "def" (concat "abc" it "ghi")) ;; => "abcdefghi"
@ -1896,6 +1921,19 @@ in second form, etc.
 (--> "def" (concat "abc" it "ghi") upcase) ;; => "ABCDEFGHI"
 ```

+#### -as-> `(value variable &rest forms)`
+
+Starting with `value`, thread `variable` through `forms`.
+
+In the first form, bind `variable` to `value`.  In the second form, bind
+`variable` to the result of the first form, and so forth.
+
+```el
+(-as-> 3 my-var (1+ my-var) (list my-var) (mapcar (lambda (ele) (* 2 ele)) my-var)) ;; => '(8)
+(-as-> 3 my-var 1+) ;; => 4
+(-as-> 3 my-var) ;; => 3
+```
+
 #### -some-> `(x &optional form &rest more)`

 When expr is non-nil, thread it through the first form (via [`->`](#--x-optional-form-rest-more)),
@ -1920,7 +1958,7 @@ and when that result is non-nil, through the next form, etc.

 #### -some--> `(x &optional form &rest more)`

-When expr in non-nil, thread it through the first form (via [`-->`](#---x-form-rest-more)),
+When expr in non-nil, thread it through the first form (via [`-->`](#---x-rest-forms)),
 and when that result is non-nil, through the next form, etc.

 ```el
@ -2479,7 +2517,7 @@ This function satisfies the following laws:
 ```el
 (funcall (-prodfn '1+ '1- 'int-to-string) '(1 2 3)) ;; => '(2 1 "3")
 (-map (-prodfn '1+ '1-) '((1 2) (3 4) (5 6) (7 8))) ;; => '((2 1) (4 3) (6 5) (8 7))
-(apply '+ (funcall (-prodfn 'length 'string-to-int) '((1 2 3) "15"))) ;; => 18
+(apply '+ (funcall (-prodfn 'length 'string-to-number) '((1 2 3) "15"))) ;; => 18
 ```


@ -2661,6 +2699,10 @@ Change `readme-template.md` or `examples-to-docs.el` instead.

 Thanks!

+New contributors are welcome. To ensure that dash.el can be
+distributed with ELPA or Emacs, we would request that all contributors
+assign copyright to the Free Software Foundation.
+
 ## License

 Copyright (C) 2012-2016 Free Software Foundation, Inc.
--- a/dash.info
+++ b/dash.info
--- a/dash.texi
+++ b/dash.texi
@ -274,7 +274,7 @@ See also: @code{-map-when} (@pxref{-map-when}), @code{-replace-first} (@pxref{-r

@anchor{-map-last}
@defun -map-last (pred rep list)
-Replace first item in @var{list} satisfying @var{pred} with result of @var{rep} called on this item.
+Replace last item in @var{list} satisfying @var{pred} with result of @var{rep} called on this item.

 See also: @code{-map-when} (@pxref{-map-when}), @code{-replace-last} (@pxref{-replace-last})

@ -2091,6 +2091,42 @@ or with @code{-compare-fn} if that's non-nil.
@end example
@end defun

+@anchor{-powerset}
+@defun -powerset (list)
+Return the power set of @var{list}.
+
+@example
+@group
+(-powerset '())
+    @result{} '(nil)
+@end group
+@group
+(-powerset '(x y z))
+    @result{} '((x y z) (x y) (x z) (x) (y z) (y) (z) nil)
+@end group
+@end example
+@end defun
+
+@anchor{-permutations}
+@defun -permutations (list)
+Return the permutations of @var{list}.
+
+@example
+@group
+(-permutations '())
+    @result{} '(nil)
+@end group
+@group
+(-permutations '(1 2))
+    @result{} '((1 2) (2 1))
+@end group
+@group
+(-permutations '(a b c))
+    @result{} '((a b c) (a c b) (b a c) (b c a) (c a b) (c b a))
+@end group
+@end example
+@end defun
+
@anchor{-distinct}
@defun -distinct (list)
 Return a new list with all duplicates removed.
@ -2524,6 +2560,10 @@ Return the first item of @var{list}, or nil on an empty list.
 (-first-item nil)
    @result{} nil
@end group
+@group
+(let ((list (list 1 2 3))) (setf (-first-item list) 5) list)
+    @result{} '(5 2 3)
+@end group
@end example
@end defun

@ -2540,6 +2580,10 @@ Return the last item of @var{list}, or nil on an empty list.
 (-last-item nil)
    @result{} nil
@end group
+@group
+(let ((list (list 1 2 3))) (setf (-last-item list) 5) list)
+    @result{} '(1 2 5)
+@end group
@end example
@end defun

@ -2878,11 +2922,12 @@ last item in second form, etc.
@end defmac

@anchor{-->}
-@defmac --> (x form &rest more)
-Thread the expr through the forms. Insert @var{x} at the position
-signified by the token @code{it} in the first form. If there are more
-forms, insert the first form at the position signified by @code{it} in
-in second form, etc.
+@defmac --> (x &rest forms)
+Starting with the value of @var{x}, thread each expression through @var{forms}.
+
+Insert @var{x} at the position signified by the token @code{it} in the first
+form.  If there are more forms, insert the first form at the position
+signified by @code{it} in in second form, etc.

@example
@group
@ -2900,6 +2945,29 @@ in second form, etc.
@end example
@end defmac

+@anchor{-as->}
+@defmac -as-> (value variable &rest forms)
+Starting with @var{value}, thread @var{variable} through @var{forms}.
+
+In the first form, bind @var{variable} to @var{value}.  In the second form, bind
+@var{variable} to the result of the first form, and so forth.
+
+@example
+@group
+(-as-> 3 my-var (1+ my-var) (list my-var) (mapcar (lambda (ele) (* 2 ele)) my-var))
+    @result{} '(8)
+@end group
+@group
+(-as-> 3 my-var 1+)
+    @result{} 4
+@end group
+@group
+(-as-> 3 my-var)
+    @result{} 3
+@end group
+@end example
+@end defmac
+
@anchor{-some->}
@defmac -some-> (x &optional form &rest more)
 When expr is non-nil, thread it through the first form (via @code{->} (@pxref{->})),
@ -3768,7 +3836,7 @@ This function satisfies the following laws:
    @result{} '((2 1) (4 3) (6 5) (8 7))
@end group
@group
-(apply '+ (funcall (-prodfn 'length 'string-to-int) '((1 2 3) "15")))
+(apply '+ (funcall (-prodfn 'length 'string-to-number) '((1 2 3) "15")))
    @result{} 18
@end group
@end example
--- a/readme-template.md
+++ b/readme-template.md
@ -248,6 +248,10 @@ Change `readme-template.md` or `examples-to-docs.el` instead.

 Thanks!

+New contributors are welcome. To ensure that dash.el can be
+distributed with ELPA or Emacs, we would request that all contributors
+assign copyright to the Free Software Foundation.
+
 ## License

 Copyright (C) 2012-2016 Free Software Foundation, Inc.