From 5af0db0c9235387baa1917359d8b1583732adda8 Mon Sep 17 00:00:00 2001 From: okamsn Date: Thu, 9 Nov 2023 21:38:22 -0500 Subject: [PATCH] Minor edits to improve the documentation of `reduce`. --- doc/loopy-doc.org | 12 +++++++----- loopy-commands.el | 10 +++++++++- 2 files changed, 16 insertions(+), 6 deletions(-) diff --git a/doc/loopy-doc.org b/doc/loopy-doc.org index f4900c97..f91799ca 100644 --- a/doc/loopy-doc.org +++ b/doc/loopy-doc.org @@ -2526,11 +2526,13 @@ The commands are described in more detail below. This command also has the alias =reducing=. - When =VAR= does not have an explicit starting value (given with the special - macro argument =with=), the first accumulated value is =EXPR=. The first - accumulated value is not the result of passing =VAR= and =EXPR= to =FUNC=. - Using the =with= special macro argument is similar to using ~cl-reduce~'s - =:initial-value= keyword argument. + Note that the first accumulated value depends on the initial value of =VAR=. + By default, the first accumulated value is the value of =EXPR=, not a result + of calling =FUNC=. However, if =VAR= has an initial value given by the =with= + special macro argument, then the first accumulated value is the result of + ~(funcall FUNC VAR EXPR)~, as also done in the subsequent steps of the loop. + This use of =with= is similar to the =:initial-value= keyword argument used by + ~cl-reduce~. #+begin_src emacs-lisp ;; => 6 diff --git a/loopy-commands.el b/loopy-commands.el index fd806e8a..dfb1e55b 100644 --- a/loopy-commands.el +++ b/loopy-commands.el @@ -2645,7 +2645,15 @@ This function is used by `loopy--expand-optimized-accum'." (loopy--defaccumulation reduce "Parse the `reduce' command as (reduce VAR VAL FUNC &key init). -With INIT, initialize VAR to INIT. Otherwise, VAR starts as nil." +With INIT, initialize VAR to INIT. Otherwise, VAR starts as nil. + +By default, the first accumulated value is the value of VAL, +not a result of calling FUNC. However, if VAR has an initial +value given by the =with= special macro argument, then the first +accumulated value is the result of `(funcall FUNC VAR VAL)', as +also done in the subsequent steps of the loop. This use of +`with' is similar to the `:initial-value' keyword argument used +by `cl-reduce'." :num-args 3 :keywords (init) :category generic