primops: make nature of foldl' strictness clearer

* Clarify the documentation of foldl': That the arguments are forced
  before application (?) of `op` is necessarily true. What is important
  to stress is that we force every application of `op`, even when the
  value turns out to be unused.

* Move the example before the comment about strictness to make it less
  confusing: It is a general example and doesn't really showcase anything
  about foldl' strictness.

* Add test cases which nail down aspects of foldl' strictness:
  * The initial accumulator value is not forced unconditionally.
  * Applications of op are forced.
  * The list elements are not forced unconditionally.

1 files changed, 3 insertions, 3 deletions

diff --git a/src/libexpr/primops.cc b/src/libexpr/primops.cc
index 28b998474..ba4b7c67a 100644
--- a/src/libexpr/primops.cc
+++ b/src/libexpr/primops.cc
@@ -2908,9 +2908,9 @@ static RegisterPrimOp primop_foldlStrict({
     .doc = R"(
       Reduce a list by applying a binary operator, from left to right,
       e.g. `foldl' op nul [x0 x1 x2 ...] = op (op (op nul x0) x1) x2)
-      ...`. The operator is applied strictly, i.e., its arguments are
-      evaluated first. For example, `foldl' (x: y: x + y) 0 [1 2 3]`
-      evaluates to 6.
+      ...`. For example, `foldl' (x: y: x + y) 0 [1 2 3]` evaluates to 6.
+      The return value of each application of `op` is evaluated immediately,
+      even for intermediate values.
     )",
     .fun = prim_foldlStrict,
 });