mirrors/phobos
1
0
Fork 0
mirror of https://github.com/dlang/phobos.git synced 2025-04-29 22:50:38 +03:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

[std.algorithm] Improve fold docs

Browse source 
Mention iteratively calling predicates in summary.
Use list to explain calling a single predicate with a seed.
Mention multiple results are produced in description.
Use list for see also.
Rename `seed` parameter `seeds` and fix docs.
Fix result docs when >1 predicate.
This commit is contained in:
Nick Treleaven 2023-10-30 16:14:10 +00:00
parent 9cb5f6d7db
commit f491d1f233
1 changed files with 26 additions and 17 deletions
Download patch file Download diff file Expand all files Collapse all files

43
std/algorithm/iteration.d
View file

@ -4809,26 +4809,34 @@ private template ReduceSeedType(E)
/++ /++
Implements the homonym function (also known as `accumulate`, $(D Implements the homonym function (also known as `accumulate`, $(D
compress), `inject`, or `foldl`) present in various programming compress), `inject`, or `foldl`) present in various programming
languages of functional flavor. The call `fold!(fun)(range, seed)` languages of functional flavor, iteratively calling one or more predicates.
first assigns `seed` to an internal variable `result`,
also called the accumulator. Then, for each element `x` in $(D $(P For a single predicate,
range), `result = fun(result, x)` gets evaluated. Finally, $(D the call `fold!(fun)(range, seed)` will:)
result) is returned. The one-argument version `fold!(fun)(range)`
* Assign `seed` to an internal variable `result` (also called the accumulator)
* For each element `e` in $(D range), evaluate `result = fun(result, e)`.
* Return $(D result).
$(P The one-argument version `fold!(fun)(range)`
works similarly, but it uses the first element of the range as the works similarly, but it uses the first element of the range as the
seed (the range must be non-empty). seed (the range must be non-empty) and iterates over the remaining
elements.)
Multiple results are produced when using multiple predicates.
Params: Params:
fun = the predicate function(s) to apply to the elements fun = the predicate function(s) to apply to the elements
See_Also: See_Also:
$(HTTP en.wikipedia.org/wiki/Fold_(higher-order_function), Fold (higher-order function)) * $(HTTP en.wikipedia.org/wiki/Fold_(higher-order_function), Fold (higher-order function))
$(LREF sum) is similar to `fold!((a, b) => a + b)` that offers * $(LREF sum) is similar to `fold!((a, b) => a + b)` that offers
precise summing of floating point numbers. precise summing of floating point numbers.
This is functionally equivalent to $(LREF reduce) with the argument order * `fold` is functionally equivalent to $(LREF reduce) with the argument order
reversed, and without the need to use $(REF_ALTTEXT `tuple`,tuple,std,typecons) reversed, and without the need to use $(REF_ALTTEXT `tuple`,tuple,std,typecons)
for multiple seeds. for multiple seeds.
+/ +/
template fold(fun...) template fold(fun...)
if (fun.length >= 1) if (fun.length >= 1)
@ -4836,20 +4844,21 @@ if (fun.length >= 1)
/** /**
Params: Params:
r = the $(REF_ALTTEXT input range, isInputRange, std,range,primitives) to fold r = the $(REF_ALTTEXT input range, isInputRange, std,range,primitives) to fold
seed = the initial value of the accumulator seeds = the initial values of each accumulator (optional), one for each predicate
Returns: Returns:
the accumulated `result` Either the accumulated result for a single predicate, or a
$(REF_ALTTEXT `Tuple`,Tuple,std,typecons) of results.
*/ */
auto fold(R, S...)(R r, S seed) auto fold(R, S...)(R r, S seeds)
{ {
static if (S.length < 2) static if (S.length < 2)
{ {
return reduce!fun(seed, r); return reduce!fun(seeds, r);
} }
else else
{ {
import std.typecons : tuple; import std.typecons : tuple;
return reduce!fun(tuple(seed), r); return reduce!fun(tuple(seeds), r);
} }
} }
} }