ReplaceByKeys function added

CHANGELOG.md

@@ -95,3 +95,6 @@
 ##8.0.0
 - **Breaking change: sum function will return integer by default, float if there are float type elements**
 - **Breaking change: average function will not force return float and will return integer if the sum/count result is integer**
+
+##8.1.0
+- ReplaceByKeys function added

README.md

@@ -1004,6 +1004,17 @@ Collection::from([1, 3, 3, 2])
 toArray(replace([1, 3, 3, 2], [3 => 'a'])); //[1, 'a', 'a', 2]
 ```
 
+#### replaceByKeys(array|Traversable $replacementMap) : Collection
+Returns a lazy collection with items from $collection, but items with keys  that are found in keys of $replacementMap are replaced by their values.
+```php
+Collection::from([1, 3, 3, 2])
+    ->replace([3 => 'a'])
+    ->toArray(); //[1, 3, 3, 'a']
+```
+```php
+toArray(replace([1, 3, 3, 2], [3 => 'a'])); //[1, 3, 3, 'a']
+```
+
 #### reverse() : Collection
 Returns a non-lazy collection of items in this collection in reverse order.
 ```php

src/CollectionTrait.php

@@ -856,6 +856,18 @@ public function toString()
         return toString($this->getItems());
     }
 
+    /**
+     * Returns a lazy collection with items from $collection, but items with keys  that are found in keys of
+     * $replacementMap are replaced by their values.
+     *
+     * @param array|\Traversable $replacementMap
+     * @return Collection
+     */
+    public function replaceByKeys($replacementMap)
+    {
+        return replaceByKeys($this->getItems(), $replacementMap);
+    }
+
     /**
      * @return array|\Traversable
      */

src/collection_functions.php

@@ -1609,3 +1609,24 @@ function toString($collection)
 
     return $result;
 }
+
+
+/**
+ * Returns a lazy collection with items from $collection, but items with keys  that are found in keys of $replacementMap
+ * are replaced by their values.
+ *
+ * @param array|Traversable $collection
+ * @param array|Traversable $replacementMap
+ * @return Collection
+ */
+function replaceByKeys($collection, $replacementMap)
+{
+    $generatorFactory = function () use ($collection, $replacementMap) {
+        foreach ($collection as $key => $value) {
+            $newValue = getOrDefault($replacementMap, $key, $value);
+            yield $key => $newValue;
+        }
+    };
+
+    return new Collection($generatorFactory);
+}

tests/spec/CollectionSpec.php

@@ -1156,7 +1156,7 @@ function it_can_get_maximal_value_in_the_colleciton()
         $this->beConstructedWith([1, 2, 3, 2]);
         $this->max()->shouldReturn(3);
     }
-    
+
     function it_will_return_null_when_max_is_called_on_empty_collection()
     {
         $this->beConstructedWith([]);
@@ -1181,6 +1181,12 @@ function it_can_convert_the_collection_to_string()
         $this->toString()->shouldReturn('2a3');
     }
 
+    function it_can_replace_by_key()
+    {
+        $this->beConstructedWith(['a' => 1, 'b' => 2, 'c' => 3]);
+        $this->replaceByKeys(['b' => 3])->toArray()->shouldReturn(['a' => 1, 'b' => 3, 'c' => 3]);
+    }
+
     function it_can_use_the_utility_methods()
     {
         $this->beConstructedWith([1, 3, 2]);
@@ -1201,6 +1207,5 @@ function it_can_use_the_utility_methods()
             ->toArray()
             ->shouldReturn([0, 2, 1]);
     }
-
 }