Add flat_map function (#78)

* Added flat_map function

* Fixed flat_map tests

* Added flat_map function

* A little fix in flat_map readme

* Modifed signature of flat_map and readme description

* Removed an space

* Modified description of flat_map example

* Added flat_map to index

* fixed flat_map comment style

docs/docs.md

@@ -16,6 +16,7 @@
  * [filter](functions/filter.md): Discriminate the items of a collection for which function is false
  * [filter_null](functions/filter_null.md): Discriminate the items of a collection for which value is null
  * [first](functions/first.md): Returns the first element of a collection
+ * [flat_map](functions/flat_map.md): Returns an array containing the results of applying a given function to the items of a collection and flattening the results
  * [flatten](functions/flatten.md): Returns a flat collection from a multidimensional collection
  * [get](functions/get.md): Returns the value of an item in a collection or a default value in the case it does not exists
  * [get_in](functions/get_in.md): Returns the value in a nested associative structure or a default value in the case it does not exists

docs/functions/flat_map.md

@@ -0,0 +1,33 @@
+# flat_map
+
+## Description
+Returns an array containing the results of applying a given function to the items of a collection and flattening the results.
+
+## Parameters
+
+<dl>
+  <dt>fn</dt>
+  <dd>Function to apply to every item in the collection. Must return a array|Traversable|Generator</dd>
+
+  <dt>coll</dt>
+  <dd>Collection of 1-n dimensions</dd>
+</dl>
+
+## Examples
+
+Create a collection of ranges and flatten the results:
+```php
+<?php
+
+use function Lambdish\Phunctional\flat_map;
+
+$range   = [2, 3, 4];
+
+$naturalRange = function ($value): array {
+    return range(1, $value);
+};
+
+return flat_map($naturalRange, $range);
+
+// => [1, 2, 1, 2, 3, 1, 2, 3, 4]
+```

src/_bootstrap.php

@@ -14,6 +14,7 @@
 require __DIR__ . '/filter.php';
 require __DIR__ . '/filter_null.php';
 require __DIR__ . '/first.php';
+require __DIR__ . '/flat_map.php';
 require __DIR__ . '/flatten.php';
 require __DIR__ . '/get.php';
 require __DIR__ . '/get_in.php';

src/flat_map.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Lambdish\Phunctional;
+
+use Generator;
+use Traversable;
+
+/**
+ * Returns an array containing the results of applying $fn to the items of the $coll
+ * and flattening the results.
+ *
+ * Function $fn should accept the value of the item as the first argument
+ * and optionally the key of the item as the second argument.
+ *
+ * @param callable                    $fn   function with signature Closure(mixed): array|Traversable|Generator
+ * @param array|Traversable|Generator $coll collection of values
+ *
+ * @return array
+ * @since  1.0.8 Added flat_map function
+ *
+ */
+function flat_map(callable $fn, $coll)
+{
+    return flatten(map($fn, $coll));
+}

tests/FlatMapTest.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace Lambdish\Phunctional\Tests;
+
+use PHPUnit_Framework_TestCase;
+use function Lambdish\Phunctional\flat_map;
+
+class FlatMapTest extends PHPUnit_Framework_TestCase
+{
+
+    /** @test */
+    public function it_should_apply_and_then_flatten()
+    {
+        $actual   = [2, 3, 4];
+        $expected = [1, 2, 1, 2, 3, 1, 2, 3, 4];
+
+        $naturalRange = function ($value) {
+            return range(1, $value);
+        };
+
+        $this->assertSame($expected, flat_map($naturalRange, $actual));
+    }
+
+    /** @test */
+    public function it_should_allow_receive_the_key_in_the_function_to_apply()
+    {
+        $actual   = [4 => 1, 9 => 5];
+        $expected = [1, 2, 3, 4, 5, 6, 7, 8, 9];
+
+        $this->assertSame($expected, flat_map('range', $actual));
+    }
+}