diff --git a/src/pages/api/std/Array/fold.mdx b/src/pages/api/std/Array/fold.mdx new file mode 100644 index 0000000..a3e6c54 --- /dev/null +++ b/src/pages/api/std/Array/fold.mdx @@ -0,0 +1,125 @@ +--- +layout: ../../../../layouts/ApiLayout.astro +--- +import Code from "../../../../components/Code.astro" + +# `Array.fold` + +Reduces the elements of this array into a single value +by calling a function on each element, starting from +the left. + +## Signature + + (B) transform_function, + ) -> B +`} /> + +## Parameters + +- `self`: The callee. +- `init`: The initial value of the fold. +- `transform_function`: The function to apply to every element. + +## Return value + +- If `self` is an empty array, returns `init` +- Otherwise, returns the result of applying `transform_function` to the accumulator `acc`, + and the next element `next`. + + +## Description + +Fold allows you to transform an array of `A` into a single `B`, following +an arbitraty function. + +For example, let's say that you have an array of numbers: + + + +And you want to join all digits into a String like `"1985"`. You can +achieve this with a fold. + + + + +- `f` is a function that takes a previous value (known as the accumulator) + and a new value (known as `next`) and concatenates them. + So `f("", 1)` results in `"1"`, `f("1", 2)` in `"12"` and so on. + +--- + +- To begin, the accumulator is set to `init`, in this case `""` +- First, `f` is called with the accumulator (`""`) and the first + element of the array (`1`) resulting in `f("", 1)` +- This results in the string `"1"`. This becomes the new value of the accumulator. +- Then `f` is called with the accumulator and the 2nd element of the array. + This results in `f("1", 9)`, which is `"19"`. This is now the accumulator. +- Then, `f` is called the same way as before, resulting in `f("19", 8)`. + The accumulator now is `"198"`. +- Finally, `f` is called the same way, resulting in `f("198", 5)` which is `"1985"`. + This is the value that `fold` returns. + +A sort of visualization is the following: + +```php +[1, 9, 8, 5].fold("", f) = + f( f( f( f("", 1), 9), 8), 5) + f( f( f( "1" , 9), 8), 5) + f( f( "19" , 8), 5) + f( "198" , 5) + "1985" +``` + +Hopefully now you understand how a fold works, and we can continue using the +abstraction. + +--- + +The `transform_function` can be any function, and can operate over any type. + +For example, you could sum all numbers instead of concatenating +like this: + + + +```php +f( f( f( f(0, 1), 9), 8), 5) +f( f( f( 1 , 9), 8), 5) +f( f( 10 , 8), 5) +f( 18 , 5) + 23 +``` + +Or you could pass the digits to a builder class: + + + +Or anything. + + + + +