Add flatten, flattenLevel

Author: mpajunen

docs/Functions.md

@@ -1,6 +1,6 @@
 # Phamda functions
 
-Currently included functions (100):
+Currently included functions (102):
 
 * [_](#_)
 * [add](#add)
@@ -39,6 +39,8 @@ Currently included functions (100):
 * [findLast](#findLast)
 * [findLastIndex](#findLastIndex)
 * [first](#first)
+* [flatten](#flatten)
+* [flattenLevel](#flattenLevel)
 * [flip](#flip)
 * [groupBy](#groupBy)
 * [gt](#gt)
@@ -586,6 +588,30 @@ Phamda::first([]); // => false
 ```
 
 
+<a name="flatten"></a>
+### flatten
+`array Phamda::flatten(array $list)`
+
+Returns an array that contains all the items on the `list`, with all arrays flattened.
+##### Examples
+```php
+Phamda::flatten([1, [2, 3], [4]]); // => [1, 2, 3, 4]
+Phamda::flatten([1, [2, [3]], [[4]]]); // => [1, 2, 3, 4]
+```
+
+
+<a name="flattenLevel"></a>
+### flattenLevel
+`array Phamda::flattenLevel(array $list)`
+
+Returns an array that contains all the items on the `list`, with arrays on the first nesting level flattened.
+##### Examples
+```php
+Phamda::flattenLevel([1, [2, 3], [4]]); // => [1, 2, 3, 4]
+Phamda::flattenLevel([1, [2, [3]], [[4]]]); // => [1, 2, [3], [4]]
+```
+
+
 <a name="flip"></a>
 ### flip
 `callable Phamda::flip(callable $function)`

src/CoreFunctionsTrait.php

@@ -143,6 +143,26 @@ protected static function _filter(callable $predicate, $collection)
         return $result;
     }
 
+    /**
+     * @param array $list
+     * @param bool  $recursive
+     *
+     * @return array
+     */
+    protected static function _flatten(array $list, $recursive)
+    {
+        $result = [];
+        foreach ($list as $item) {
+            if (is_array($item)) {
+                $result = array_merge($result, $recursive ? self::_flatten($item, $recursive) : $item);
+            } else {
+                $result[] = $item;
+            }
+        }
+
+        return $result;
+    }
+
     /**
      * @param callable                      $function
      * @param array|\Traversable|Collection $collection

src/Phamda.php

@@ -880,6 +880,44 @@ public static function first($collection = null)
         }, func_get_args());
     }
 
+    /**
+     * Returns an array that contains all the items on the `list`, with all arrays flattened.
+     *
+     * ```php
+     * Phamda::flatten([1, [2, 3], [4]]); // => [1, 2, 3, 4]
+     * Phamda::flatten([1, [2, [3]], [[4]]]); // => [1, 2, 3, 4]
+     * ```
+     *
+     * @param array $list
+     *
+     * @return callable|array
+     */
+    public static function flatten($list = null)
+    {
+        return static::curry1(function (array $list) {
+            return static::_flatten($list, true);
+        }, func_get_args());
+    }
+
+    /**
+     * Returns an array that contains all the items on the `list`, with arrays on the first nesting level flattened.
+     *
+     * ```php
+     * Phamda::flattenLevel([1, [2, 3], [4]]); // => [1, 2, 3, 4]
+     * Phamda::flattenLevel([1, [2, [3]], [[4]]]); // => [1, 2, [3], [4]]
+     * ```
+     *
+     * @param array $list
+     *
+     * @return callable|array
+     */
+    public static function flattenLevel($list = null)
+    {
+        return static::curry1(function (array $list) {
+            return static::_flatten($list, false);
+        }, func_get_args());
+    }
+
     /**
      * Wraps the given function and returns a new function for which the order of the first two parameters is reversed.
      *

tests/BasicProvidersTrait.php

@@ -405,6 +405,22 @@ public function getFirstData()
         ];
     }
 
+    public function getFlattenData()
+    {
+        return [
+            [[1, 2, 3, 4], [1, [2, 3], [4]]],
+            [[1, 2, 3, 4], [1, [2, [3]], [[4]]]],
+        ];
+    }
+
+    public function getFlattenLevelData()
+    {
+        return [
+            [[1, 2, 3, 4], [1, [2, 3], [4]]],
+            [[1, 2, [3], [4]], [1, [2, [3]], [[4]]]],
+        ];
+    }
+
     public function getFlipData()
     {
         $subMany = function ($a, $b, $c = 0, $d = 0, $e = 0) {

tests/BasicTest.php

@@ -415,6 +415,26 @@ public function testFirst($expected, $collection)
         $this->assertSame($expected, $curried0($collection), 'first is curried correctly.');
     }
 
+    /**
+     * @dataProvider getFlattenData
+     */
+    public function testFlatten($expected, array $list)
+    {
+        $this->assertSame($expected, Phamda::flatten($list), 'flatten produces correct results.');
+        $curried0 = Phamda::flatten();
+        $this->assertSame($expected, $curried0($list), 'flatten is curried correctly.');
+    }
+
+    /**
+     * @dataProvider getFlattenLevelData
+     */
+    public function testFlattenLevel($expected, array $list)
+    {
+        $this->assertSame($expected, Phamda::flattenLevel($list), 'flattenLevel produces correct results.');
+        $curried0 = Phamda::flattenLevel();
+        $this->assertSame($expected, $curried0($list), 'flattenLevel is curried correctly.');
+    }
+
     /**
      * @dataProvider getFlipData
      */