Add get_each function (#88)

* get_each function returns an array with the values or a $default value in the case it does not exist of each item in a $coll * Fixed the error analysing code in get_each.php, parameter #1 $key of function Lambdish\Phunctional\_get_values_from_key expects string, int|string given. * get_each function documentation * get_each function will return an empty array when no item contains the expected key.
Lambdish · Sep 18, 2020 · ed3482e · ed3482e
1 parent 133c298
commit ed3482e
Show file tree

Hide file tree

Showing 5 changed files with 255 additions and 0 deletions.
diff --git a/docs/docs.md b/docs/docs.md
@@ -20,6 +20,7 @@
  * [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_each](functions/get_each.md): Returns an array with the values or a default value in the case it does not exist of each item in a collection
  * [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
  * [group_by](functions/group_by.md): Returns an array with the items grouped by the results of applying a function to each item
  * [key](functions/key.md): Returns the key of an item value in a collection or a default value in the case it does not exists

diff --git a/docs/functions/get_each.md b/docs/functions/get_each.md
@@ -0,0 +1,68 @@
+# get_each
+
+## Description
+Returns an array with the values of the key of each item in a collection. An empty array is returned if no item contains the key.
+
+
+## Parameters
+
+<dl>
+    <dt>key</dt>
+    <dd>Key to search in the collection.</dd>
+    <dt>coll</dt>
+    <dd>Collection where search the expected key.</dd>
+</dl>
+
+## Examples
+
+Returns an array with emails from each element of an array:
+```php
+<?php
+
+use function Lambdish\Phunctional\get_each;
+
+$users = [
+    'user1' => [
+        'name'  => 'Mike',
+        'email' => 'mike@example.com'
+    ],
+    'user2' => [
+        'name'  => 'John',
+        'email' => 'john@example.com'
+    ],
+    'user3' => [
+        'name'  => 'James',
+        'phone' => '555-555555'
+    ]
+];
+
+return get_each('email', $users);
+
+// => ['mike@example.com', 'john@example.com']
+```
+
+Returns an empty array because the expected key does not exist in any item from the collection:
+```php
+<?php
+
+use function Lambdish\Phunctional\get_each;
+
+$users = [
+    'user1' => [
+        'name'  => 'Mike',
+        'email' => 'mike@example.com'
+    ],
+    'user2' => [
+        'name'  => 'John',
+        'email' => 'john@example.com'
+    ],
+    'user3' => [
+        'name'  => 'James',
+        'phone' => '555-555555'
+    ]
+];
+
+return get_each('surname', $users);
+
+// => []
+```
diff --git a/src/_bootstrap.php b/src/_bootstrap.php
@@ -20,6 +20,7 @@
 require __DIR__ . '/flat_map.php';
 require __DIR__ . '/flatten.php';
 require __DIR__ . '/get.php';
+require __DIR__ . '/get_each.php';
 require __DIR__ . '/get_in.php';
 require __DIR__ . '/group_by.php';
 require __DIR__ . '/key.php';

diff --git a/src/get_each.php b/src/get_each.php
@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Lambdish\Phunctional;
+
+use Traversable;
+
+/**
+ * Returns an array with the values of the key of each item in a collection.
+ * An empty array is returned if no item contains the key.
+ *
+ * @param string|int $key key to search in the collection
+ * @param iterable $coll collection where search the expected key
+ *
+ * @return array
+ *
+ * @since 0.1
+ */
+function get_each($key, iterable $coll): array {
+    return apply(
+        pipe(
+            _convert_traversable_to_array(),
+            _get_values_from_key($key),
+            _remove_null_values(),
+            _reindex_array()
+        ),
+        [$coll]
+    );
+}
+
+function _convert_traversable_to_array(): callable {
+    return static function (iterable $coll): iterable {
+        return $coll instanceof Traversable ? iterator_to_array($coll) : $coll;
+    };
+}
+
+function _get_values_from_key($key): callable {
+    return static function (array $coll) use ($key): array {
+        return array_merge(...map(
+            static function (array $item) use ($key): array {
+                $value = get($key, $item, null);
+                return [$value];
+            },
+            array_values($coll)
+        ));
+    };
+}
+
+function _remove_null_values(): callable {
+    return static function (array $coll): array {
+        return filter_null($coll);
+    };
+}
+
+function _reindex_array(): callable {
+    return static function (array $coll): array {
+        return array_values($coll);
+    };
+}
+
+const get_each = '\Lambdish\Phunctional\get_each';
diff --git a/tests/GetEachTest.php b/tests/GetEachTest.php
@@ -0,0 +1,123 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Lambdish\Phunctional\Tests;
+
+use ArrayIterator;
+use PHPUnit\Framework\TestCase;
+use function Lambdish\Phunctional\get_each;
+
+final class GetEachTest extends TestCase {
+    /** @test */
+    public function it_should_return_an_array_with_values_of_each_item_of_an_existent_key_indexed_by_integers(): void {
+        $actual = [
+            [
+                'key'       => 1,
+                'other_key' => 3
+            ],
+            [
+                'key'       => 2,
+                'other_key' => 4
+            ]
+        ];
+
+        $this->assertSame([1, 2], get_each('key', $actual));
+    }
+
+    /** @test */
+    public function it_should_return_an_array_with_values_of_each_item_of_an_existent_key(): void {
+        $actual = [
+            'one' => [
+                'key'       => 1,
+                'other_key' => 3
+            ],
+            'two' => [
+                'key'       => 2,
+                'other_key' => 4
+            ]
+        ];
+
+        $this->assertSame([1, 2], get_each('key', $actual));
+    }
+
+    /** @test */
+    public function it_should_return_an_array_with_values_of_each_item_of_an_existent_property_of_a_traversable(): void {
+        $traversable = new ArrayIterator([
+            'one' => [
+                'key'       => 1,
+                'other_key' => 3
+            ],
+            'two' => [
+                'key'       => 2,
+                'other_key' => 4
+            ]
+        ]);
+
+        $this->assertSame([1, 2], get_each('key', $traversable));
+    }
+
+    /** @test */
+    public function it_should_return_an_empty_array_if_the_key_does_not_exist(): void {
+        $actual = [
+            'one' => [
+                'key'       => 1,
+                'other_key' => 3
+            ],
+            'two' => [
+                'key'       => 2,
+                'other_key' => 4
+            ]
+        ];
+
+        $this->assertSame([], get_each('not_existing_key', $actual));
+    }
+
+    /** @test */
+    public function it_should_return_an_empty_array_if_the_property_does_not_exist(): void {
+        $traversable = new ArrayIterator([
+            'one' => [
+                'key'       => 1,
+                'other_key' => 3
+            ],
+            'two' => [
+                'key'       => 2,
+                'other_key' => 4
+            ]
+        ]);
+
+        $this->assertSame([], get_each('not_existing_key', $traversable));
+    }
+
+    /** @test */
+    public function it_should_return_an_array_with_values_of_each_item_of_an_existent_false_value(): void {
+        $actual = [
+            'one' => [
+                'key'       => null,
+                'other_key' => true
+            ],
+            'two' => [
+                'key'       => false,
+                'other_key' => true
+            ]
+        ];
+
+        $this->assertSame([false], get_each('key', $actual));
+    }
+
+    /** @test */
+    public function it_should_return_an_array_with_values_of_each_item_of_an_existent_false_property_of_a_traversable(): void {
+        $traversable = new ArrayIterator([
+            'one' => [
+                'key'       => null,
+                'other_key' => true
+            ],
+            'two' => [
+                'key'       => false,
+                'other_key' => true
+            ]
+        ]);
+
+        $this->assertSame([false], get_each('key', $traversable));
+    }
+}