Add flatMap

Author: mpajunen

docs/Functions.md

@@ -1,6 +1,6 @@
 # Phamda functions
 
-Currently included functions (102):
+Currently included functions (103):
 
 * [_](#_)
 * [add](#add)
@@ -39,6 +39,7 @@ Currently included functions (102):
 * [findLast](#findLast)
 * [findLastIndex](#findLastIndex)
 * [first](#first)
+* [flatMap](#flatMap)
 * [flatten](#flatten)
 * [flattenLevel](#flattenLevel)
 * [flip](#flip)
@@ -588,6 +589,18 @@ Phamda::first([]); // => false
 ```
 
 
+<a name="flatMap"></a>
+### flatMap
+`array Phamda::flatMap(callable $function, array $list)`
+
+Returns a list containing the flattened items created by applying the `function` to each item of the `list`.
+##### Examples
+```php
+$split = function ($string) { return str_split($string); };
+Phamda::flatMap($split, ['abc', 'de']); // => ['a', 'b', 'c', 'd', 'e']
+```
+
+
 <a name="flatten"></a>
 ### flatten
 `array Phamda::flatten(array $list)`

src/Phamda.php

@@ -880,6 +880,26 @@ public static function first($collection = null)
         }, func_get_args());
     }
 
+    /**
+     * Returns a list containing the flattened items created by applying the `function` to each item of the `list`.
+     *
+     * ```php
+     * $split = function ($string) { return str_split($string); };
+     * Phamda::flatMap($split, ['abc', 'de']); // => ['a', 'b', 'c', 'd', 'e']
+     * ```
+     *
+     * @param callable $function
+     * @param array    $list
+     *
+     * @return callable|array
+     */
+    public static function flatMap($function = null, $list = null)
+    {
+        return static::curry2(function (callable $function, array $list) {
+            return static::_flatten(static::_map($function, $list), false);
+        }, func_get_args());
+    }
+
     /**
      * Returns an array that contains all the items on the `list`, with all arrays flattened.
      *

tests/BasicProvidersTrait.php

@@ -405,6 +405,15 @@ public function getFirstData()
         ];
     }
 
+    public function getFlatMapData()
+    {
+        $duplicate = function ($x) { return [$x, $x]; };
+
+        return [
+            [[2, 2, 3, 3, 6, 6], $duplicate, [2, 3, 6]],
+        ];
+    }
+
     public function getFlattenData()
     {
         return [

tests/BasicTest.php

@@ -415,6 +415,18 @@ public function testFirst($expected, $collection)
         $this->assertSame($expected, $curried0($collection), 'first is curried correctly.');
     }
 
+    /**
+     * @dataProvider getFlatMapData
+     */
+    public function testFlatMap($expected, callable $function, array $list)
+    {
+        $this->assertSame($expected, Phamda::flatMap($function, $list), 'flatMap produces correct results.');
+        $curried0 = Phamda::flatMap();
+        $this->assertSame($expected, $curried0($function, $list), 'flatMap is curried correctly.');
+        $curried1 = Phamda::flatMap($function);
+        $this->assertSame($expected, $curried1($list), 'flatMap is curried correctly.');
+    }
+
     /**
      * @dataProvider getFlattenData
      */

tests/FunctionExampleTest.php

@@ -188,6 +188,12 @@ public function testFindLastIndex()
         $this->assertSame(3, Phamda::findLastIndex($isPositive, [-5, 0, 15, 33, -2]));
     }
 
+    public function testFlatMap()
+    {
+        $split = function ($string) { return str_split($string); };
+        $this->assertSame(['a', 'b', 'c', 'd', 'e'], Phamda::flatMap($split, ['abc', 'de']));
+    }
+
     public function testFlip()
     {
         $sub        = function ($x, $y) { return $x - $y; };