Write -iterate in terms of --iterate

* dash.el (--iterate): Implement in terms of dotimes.  Move
definition before first use.
(-iterate): Implement in terms of --iterate.
* dev/examples.el (Unfolding): Fix group description.
(-iterate): Add more tests.

* README.md:
* dash.texi: Regenerate docs.

README.md

@@ -178,7 +178,7 @@ Functions reducing lists into single value.
 ### Unfolding
 
 
-Operations dual to reductions, building lists from seed value rather than consuming a list to produce a single value.
+Operations dual to reductions, building lists from a seed value rather than consuming a list to produce a single value.
 
 * [-iterate](#-iterate-fun-init-n) `(fun init n)`
 * [-unfold](#-unfold-fun-seed) `(fun seed)`
@@ -1161,20 +1161,20 @@ comparing them.
 ## Unfolding
 
 
-Operations dual to reductions, building lists from seed value rather than consuming a list to produce a single value.
+Operations dual to reductions, building lists from a seed value rather than consuming a list to produce a single value.
 
 #### -iterate `(fun init n)`
 
 Return a list of iterated applications of `fun` to `init`.
 
-This means a list of form:
+This means a list of the form:
 
-    (init (fun init) (fun (fun init)) ...)
+    (`init` (`fun` `init`) (`fun` (`fun` `init`)) ...)
 
 `n` is the length of the returned list.
 
 ```el
-(-iterate '1+ 1 10) ;; => '(1 2 3 4 5 6 7 8 9 10)
+(-iterate #'1+ 1 10) ;; => '(1 2 3 4 5 6 7 8 9 10)
 (-iterate (lambda (x) (+ x x)) 2 5) ;; => '(2 4 8 16 32)
 (--iterate (* it it) 2 5) ;; => '(2 4 16 256 65536)
 ```

dash.el

@@ -522,6 +522,26 @@ See also: `-map-last'"
 Thus function FN should return a list."
   (--mapcat (funcall fn it) list))
 
+(defmacro --iterate (form init n)
+  "Anaphoric version of `-iterate'."
+  (declare (debug (form form form)))
+  (let ((res (make-symbol "result")))
+    `(let ((it ,init) ,res)
+       (dotimes (_ ,n)
+         (push it ,res)
+         (setq it ,form))
+       (nreverse ,res))))
+
+(defun -iterate (fun init n)
+  "Return a list of iterated applications of FUN to INIT.
+
+This means a list of the form:
+
+  (INIT (FUN INIT) (FUN (FUN INIT)) ...)
+
+N is the length of the returned list."
+  (--iterate (funcall fun it) init n))
+
 (defun -flatten (l)
   "Take a nested list L and return its contents as a single, flat list.
 
@@ -539,11 +559,6 @@ See also: `-flatten-n'"
       (-mapcat '-flatten l)
     (list l)))
 
-(defmacro --iterate (form init n)
-  "Anaphoric version of `-iterate'."
-  (declare (debug (form form form)))
-  `(-iterate (lambda (it) ,form) ,init ,n))
-
 (defun -flatten-n (num list)
   "Flatten NUM levels of a nested LIST.
 
@@ -2545,20 +2560,6 @@ The items for the comparator form are exposed as \"it\" and \"other\"."
   (declare (debug (form form)))
   `(-min-by (lambda (it other) ,form) ,list))
 
-(defun -iterate (fun init n)
-  "Return a list of iterated applications of FUN to INIT.
-
-This means a list of form:
-
-  (init (fun init) (fun (fun init)) ...)
-
-N is the length of the returned list."
-  (if (= n 0) nil
-    (let ((r (list init)))
-      (--dotimes (1- n)
-        (push (funcall fun (car r)) r))
-      (nreverse r))))
-
 (defun -fix (fn list)
   "Compute the (least) fixpoint of FN with initial input LIST.
 

dash.texi

@@ -1602,22 +1602,22 @@ comparing them.
 @section Unfolding
 
 
-Operations dual to reductions, building lists from seed value rather than consuming a list to produce a single value.
+Operations dual to reductions, building lists from a seed value rather than consuming a list to produce a single value.
 
 
 @anchor{-iterate}
 @defun -iterate (fun init n)
 Return a list of iterated applications of @var{fun} to @var{init}.
 
-This means a list of form:
+This means a list of the form:
 
-    (init (fun init) (fun (fun init)) @dots{})
+    (@var{init} (@var{fun} @var{init}) (@var{fun} (@var{fun} @var{init})) @dots{})
 
 @var{n} is the length of the returned list.
 
 @example
 @group
-(-iterate '1+ 1 10)
+(-iterate #'1+ 1 10)
     @result{} '(1 2 3 4 5 6 7 8 9 10)
 @end group
 @group

dev/examples.el

@@ -501,12 +501,21 @@ new list."
     (--max-by (> (length it) (length other)) '((1 2 3) (2) (3 2))) => '(1 2 3)))
 
 (def-example-group "Unfolding"
-  "Operations dual to reductions, building lists from seed value rather than consuming a list to produce a single value."
+  "Operations dual to reductions, building lists from a seed value rather than \
+consuming a list to produce a single value."
 
   (defexamples -iterate
-    (-iterate '1+ 1 10) => '(1 2 3 4 5 6 7 8 9 10)
+    (-iterate #'1+ 1 10) => '(1 2 3 4 5 6 7 8 9 10)
     (-iterate (lambda (x) (+ x x)) 2 5) => '(2 4 8 16 32)
-    (--iterate (* it it) 2 5) => '(2 4 16 256 65536))
+    (--iterate (* it it) 2 5) => '(2 4 16 256 65536)
+    (-iterate #'1+ 1 0) => ()
+    (-iterate #'1+ 1 -1) => ()
+    (-iterate #'ignore 1 1) => '(1)
+    (-iterate #'ignore 1 3) => '(1 nil nil)
+    (--iterate nil nil 0) => ()
+    (--iterate nil nil 1) => '(nil)
+    (--iterate nil nil 2) => '(nil nil)
+    (--iterate (setq it -1) 1 3) => '(1 -1 -1))
 
   (defexamples -unfold
     (-unfold (lambda (x) (unless (= x 0) (cons x (1- x)))) 10) => '(10 9 8 7 6 5 4 3 2 1)