Add toArrayPreservingKeys (#126)

Author: sanmai

README.md

@@ -125,6 +125,7 @@ All entry points always return an instance of the pipeline.
 | `max()`     | Finds the highest value. | `max` |
 | `min()`     | Finds the lowest value. | `min` |
 | `toArray()` | Returns an array with all values. Eagerly executed. | `dict`, `ToDictionary` |
+| `toArrayPreservingKeys()` | Returns an array with all values and keys. Eagerly executed. |  |
 | `runningVariance()` | Computes online statistics: sample mean, sample variance, standard deviation. | [Welford's method](https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance#Welford's_online_algorithm) |
 | `finalVariance()` | Computes final statistics for the sequence. |   |
 | `__construct()` | Can be provided with an optional initial iterator. Used in the `take()` function from above.  |     |

src/Standard.php

@@ -539,6 +539,14 @@ public function toArray(bool $preserve_keys = false): array
         return iterator_to_array($this, $preserve_keys);
     }
 
+    /**
+     * Returns all values preserving keys. This is a terminal operation.
+     */
+    public function toArrayPreservingKeys(): array
+    {
+        return $this->toArray(true);
+    }
+
     /**
      * {@inheritdoc}
      *

tests/StandardTest.php

@@ -369,6 +369,19 @@ public function testToArrayWithArray(): void
         ], $pipeline->toArray(true));
     }
 
+    public function testToArrayWithArrayPreservingKeys(): void
+    {
+        $pipeline = fromArray([
+            'a' => 1,
+            'b' => 2,
+        ]);
+
+        $this->assertSame([
+            'a' => 1,
+            'b' => 2,
+        ], $pipeline->toArrayPreservingKeys());
+    }
+
     public function testToArrayWithIterator(): void
     {
         $pipeline = map(function () {
@@ -391,4 +404,18 @@ public function testToArrayWithIterator(): void
             'b' => 2,
         ], $pipeline->toArray(true));
     }
+
+    public function testToArrayWithIteratorPreservingKeys(): void
+    {
+        $pipeline = map(function () {
+            yield 'a' => 1;
+            yield 'b' => 2;
+            yield 'b' => 3;
+        });
+
+        $this->assertSame([
+            'a' => 1,
+            'b' => 3,
+        ], $pipeline->toArrayPreservingKeys());
+    }
 }