From f25a9781bdf1672e61ac3547980b16a7fc0be9ce Mon Sep 17 00:00:00 2001
From: Fernando Pradas <5954976+fnandot@users.noreply.github.com>
Date: Thu, 4 Jul 2019 09:29:16 +0200
Subject: [PATCH] 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               |  1 +
 docs/functions/flat_map.md | 33 +++++++++++++++++++++++++++++++++
 src/_bootstrap.php         |  1 +
 src/flat_map.php           | 25 +++++++++++++++++++++++++
 tests/FlatMapTest.php      | 32 ++++++++++++++++++++++++++++++++
 5 files changed, 92 insertions(+)
 create mode 100644 docs/functions/flat_map.md
 create mode 100644 src/flat_map.php
 create mode 100644 tests/FlatMapTest.php

diff --git a/docs/docs.md b/docs/docs.md
index 8ea226f..bfb1e07 100644
--- a/docs/docs.md
+++ b/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
diff --git a/docs/functions/flat_map.md b/docs/functions/flat_map.md
new file mode 100644
index 0000000..ab5cf50
--- /dev/null
+++ b/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]
+```
diff --git a/src/_bootstrap.php b/src/_bootstrap.php
index aba10b0..0ab8a7e 100644
--- a/src/_bootstrap.php
+++ b/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';
diff --git a/src/flat_map.php b/src/flat_map.php
new file mode 100644
index 0000000..608e69a
--- /dev/null
+++ b/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));
+}
diff --git a/tests/FlatMapTest.php b/tests/FlatMapTest.php
new file mode 100644
index 0000000..3eee078
--- /dev/null
+++ b/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));
+    }
+}