add select_keys for dissecting assoc arrays (lstrojny#145)

rodnaph · lstrojny · commit dac3eea4cf16 · 2017-07-04T17:33:25.000+02:00
* add select_keys for dissecting assoc arrays

* support Traversable in select_keys

* add docs for select_keys
diff --git a/composer.json b/composer.json
@@ -90,6 +90,7 @@
             "src/Functional/Reject.php",
             "src/Functional/Retry.php",
             "src/Functional/Select.php",
+            "src/Functional/SelectKeys.php",
             "src/Functional/SequenceConstant.php",
             "src/Functional/SequenceExponential.php",
             "src/Functional/SequenceLinear.php",
diff --git a/docs/functional-php.md b/docs/functional-php.md
@@ -36,6 +36,7 @@
   - [first_index_of()](#first_index_of)
   - [last_index_of()](#last_index_of)
   - [indexes_of()](#indexes_of)
+  - [select_keys()](#select_keys)
 - [Function functions](#function-functions)
   - [retry()](#retry)
   - [poll()](#poll)
@@ -610,6 +611,19 @@ use function Functional\indexes_of;
 $indexes = indexes_of(['value', 'value2', 'value'], 'value');
 ```
 
+## select_keys()
+
+Returns an array containing only those entries in the array/Traversable whose key is in the supplied keys.
+
+```php
+<?php
+
+use function Functional\select_keys;
+
+// $array will be ['foo' => 1, 'baz' => 3]
+$array = select_keys(['foo' => 1, 'bar' => 2', 'baz' => 3], ['foo', 'baz']);
+```
+
 # Function functions
 
 Function functions take a function or functions and return a new, modified version of the function.
diff --git a/src/Functional/SelectKeys.php b/src/Functional/SelectKeys.php
@@ -0,0 +1,46 @@
+<?php
+/**
+ * Copyright (C) 2011-2017 by Lars Strojny <lstrojny@php.net>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+namespace Functional;
+
+use Functional\Exceptions\InvalidArgumentException;
+use Traversable;
+
+/**
+ * Select the specified keys from the array
+ *
+ * @param Traversable|array $collection
+ * @param array $keys
+ * @return array
+ */
+function select_keys($collection, array $keys)
+{
+    InvalidArgumentException::assertCollection($collection, __FUNCTION__, 1);
+
+    if ($collection instanceof Traversable) {
+        $array = iterator_to_array($collection);
+    } else {
+        $array = $collection;
+    }
+
+    return \array_intersect_key($array, \array_flip($keys));
+}
diff --git a/tests/Functional/SelectKeysTest.php b/tests/Functional/SelectKeysTest.php
@@ -0,0 +1,55 @@
+<?php
+/**
+ * Copyright (C) 2011-2017 by Lars Strojny <lstrojny@php.net>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the 'Software'), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+namespace Functional\Tests;
+
+use ArrayIterator;
+use function Functional\select_keys;
+
+class SelectKeysTest extends AbstractTestCase
+{
+    public static function getData()
+    {
+        return [
+            [[], ['foo' => 1], []],
+            [[], ['foo' => 1], ['bar']],
+            [['foo' => 1], ['foo' => 1], ['foo']],
+            [['foo' => 1, 'bar' => 2], ['foo' => 1, 'bar' => 2], ['foo', 'bar']],
+            [[0 => 'a', 2 => 'c'], ['a', 'b', 'c'], [0, 2]],
+        ];
+    }
+
+    /**
+     * @dataProvider getData
+     */
+    public function test(array $expected, array $input, array $keys)
+    {
+        $this->assertSame($expected, select_keys($input, $keys));
+        $this->assertSame($expected, select_keys(new ArrayIterator($input), $keys));
+    }
+
+    public function testPassNonArrayOrTraversable()
+    {
+        $this->expectArgumentError("Functional\select_keys() expects parameter 1 to be array or instance of Traversable");
+        select_keys(new \stdclass(), []);
+    }
+}
