Add juxt for applying multiple functions to the same arguments (#263)

Author: phanan

composer.json

@@ -74,6 +74,7 @@
             "src/Functional/InvokeIf.php",
             "src/Functional/InvokeLast.php",
             "src/Functional/Invoker.php",
+            "src/Functional/Juxt.php",
             "src/Functional/Last.php",
             "src/Functional/LastIndexOf.php",
             "src/Functional/LessThan.php",

docs/functional-php.md

@@ -329,6 +329,23 @@ use function Functional\partial_method;
 $registeredUsers = select($users, partial_method('isRegistered'));
 ```
 
+## juxt()
+Takes a list of functions and returns a new function that applies each function to the given arguments and returns an array of the results. Inspired by Clojure's `juxt`.
+
+``callable Functional\juxt(callable ...$functions)``
+
+```php
+use function Functional\juxt;
+
+$getStats = juxt('min', 'max');
+$getStats(3, 1, 5, 2); // [1, 5]
+
+$transform = juxt('strtoupper', 'strtolower', 'strrev');
+$transform('Hello'); // ['HELLO', 'hello', 'olleH']
+```
+
+_See also `converge()`, which additionally passes the results through a converging function._
+
 ## converge()
 
 ``callable Functional\converge(callable $convergingFunction, callable[] branchingFunctions)``

src/Functional/Functional.php

@@ -237,6 +237,11 @@ final class Functional
      */
     const invoker = '\Functional\invoker';
 
+    /**
+     * @see \Functional\juxt
+     */
+    const juxt = '\Functional\juxt';
+
     /**
      * @see \Functional\last
      */

src/Functional/Juxt.php

@@ -0,0 +1,32 @@
+<?php
+
+/**
+ * @package   Functional-php
+ * @author    Lars Strojny <lstrojny@php.net>
+ * @copyright 2011-2021 Lars Strojny
+ * @license   https://opensource.org/licenses/MIT MIT
+ * @link      https://github.com/lstrojny/functional-php
+ */
+
+namespace Functional;
+
+/**
+ * Takes a list of functions and returns a new function that applies each
+ * function to the given arguments and returns an array of the results.
+ *
+ * @param callable ...$functions
+ * @return callable
+ * @no-named-arguments
+ */
+function juxt(callable ...$functions)
+{
+    return function (...$values) use ($functions) {
+        $result = [];
+
+        foreach ($functions as $function) {
+            $result[] = $function(...$values);
+        }
+
+        return $result;
+    };
+}

tests/Functional/JuxtTest.php

@@ -0,0 +1,68 @@
+<?php
+
+/**
+ * @package   Functional-php
+ * @author    Lars Strojny <lstrojny@php.net>
+ * @copyright 2011-2021 Lars Strojny
+ * @license   https://opensource.org/licenses/MIT MIT
+ * @link      https://github.com/lstrojny/functional-php
+ */
+
+namespace Functional\Tests;
+
+use function Functional\juxt;
+
+class JuxtTest extends AbstractTestCase
+{
+    public function test(): void
+    {
+        $juxted = juxt('strtoupper', 'strtolower', 'strrev');
+
+        self::assertSame(['HELLO', 'hello', 'olleH'], $juxted('Hello'));
+    }
+
+    public function testWithMultipleArguments(): void
+    {
+        $minMax = juxt('min', 'max');
+
+        self::assertSame([1, 5], $minMax(3, 1, 5, 2));
+    }
+
+    public function testWithArrayFunctions(): void
+    {
+        $stats = juxt('array_sum', 'count');
+
+        self::assertSame([15, 5], $stats([1, 2, 3, 4, 5]));
+    }
+
+    public function testWithClosures(): void
+    {
+        $double = static function ($x) {
+            return $x * 2;
+        };
+        $square = static function ($x) {
+            return $x * $x;
+        };
+        $negate = static function ($x) {
+            return -$x;
+        };
+
+        $juxted = juxt($double, $square, $negate);
+
+        self::assertSame([10, 25, -5], $juxted(5));
+    }
+
+    public function testWithNoFunctions(): void
+    {
+        $juxted = juxt();
+
+        self::assertSame([], $juxted('anything'));
+    }
+
+    public function testWithSingleFunction(): void
+    {
+        $juxted = juxt('strlen');
+
+        self::assertSame([5], $juxted('hello'));
+    }
+}