Added reindex function

README.md

@@ -35,6 +35,7 @@ list the function signatures as an overview:
 
     Iterator map(callable $function, iterable $iterable)
     Iterator mapKeys(callable $function, iterable $iterable)
+    Iterator reindex(callable $function, iterable $iterable)
     Iterator filter(callable $predicate, iterable $iterable)
     Iterator zip(iterable... $iterables)
     Iterator zipKeyValue(iterable $keys, iterable $values)

src/iter.php

@@ -107,6 +107,37 @@ function mapKeys(callable $function, $iterable) {
     }
 }
 
+/**
+ * Reindexes an array by applying a function to all values of an iterator and
+ * using the returned value as the new key/index.
+ *
+ * The function is passed the current iterator value and should return a new
+ * key for that element. The value is left as-is. The original key is not passed
+ * to the mapping function.
+ *
+ * Examples:
+ *
+ *     $users = [
+ *         ['id' => 42, 'name' => 'foo'],
+ *         ['id' => 24, 'name' => 'bar']
+ *     ];
+ *     iter\reindex(iter\fn\index('id'), $users)
+ *     => iter(
+ *         42 => ['id' => 42, 'name' => 'foo'],
+ *         24 => ['id' => 24, 'name' => 'bar']
+ *     )
+ *
+ * @param callable $function Mapping function mixed function(mixed $value)
+ * @param mixed    $iterable Iterable to reindex
+ *
+ * @return \Iterator
+ */
+function reindex(callable $function, $iterable) {
+    foreach ($iterable as $value) {
+        yield $function($value) => $value;
+    }
+}
+
 /**
  * Applies a function to all values of an iterable.
  *

src/iter.rewindable.php

@@ -55,6 +55,7 @@ function callRewindable(callable $function /*, ... $args */) {
     function range()       { return new _RewindableGenerator('iter\range',       func_get_args()); }
     function map()         { return new _RewindableGenerator('iter\map',         func_get_args()); }
     function mapKeys()     { return new _RewindableGenerator('iter\mapKeys',     func_get_args()); }
+    function reindex()     { return new _RewindableGenerator('iter\reindex',     func_get_args()); }
     function filter()      { return new _RewindableGenerator('iter\filter',      func_get_args()); }
     function zip()         { return new _RewindableGenerator('iter\zip',         func_get_args()); }
     function zipKeyValue() { return new _RewindableGenerator('iter\zipKeyValue', func_get_args()); }
@@ -81,6 +82,7 @@ function chunk()       { return new _RewindableGenerator('iter\chunk',       fun
     class _RewindableGenerator implements \Iterator {
         protected $function;
         protected $args;
+        /** @var \Generator */
         protected $generator;
 
         public function __construct(callable $function, array $args) {

test/IterRewindableTest.php

@@ -25,6 +25,11 @@ public function testRewindableVariants() {
             rewindable\mapKeys('strtolower', ['A' => 1, 'B' => 2, 'C' => 3]),
             true
         );
+        $this->assertRewindableEquals(
+            [2 => 1, 4 => 2, 6 => 3, 8 => 4],
+            rewindable\reindex(fn\operator('*', 2), [1, 2, 3, 4]),
+            true
+        );
         $this->assertRewindableEquals(
             [-5, -4, -3, -2, -1],
             rewindable\filter(fn\operator('<', 0), rewindable\range(-5, 5))

test/iterTest.php

@@ -57,6 +57,20 @@ public function testMapKeys() {
         );
     }
 
+    public function testReindex() {
+        $iter = reindex('strtoupper', ['a', 'b', 'c', 'd', 'e']);
+        $this->assertSame(
+            ['A' => 'a', 'B' => 'b', 'C' => 'c', 'D' => 'd', 'E' => 'e'],
+            toArrayWithKeys($iter)
+        );
+
+        $iter = reindex(fn\operator('*', 2), [1, 2, 3, 4]);
+        $this->assertSame(
+            [2 => 1, 4 => 2, 6 => 3, 8 => 4],
+            toArrayWithKeys($iter)
+        );
+    }
+
     public function testApply() {
         $range = range(0, 5);
         $result = [];