Allow addition of multiple values and collection merging/combining

src/Collections/Collection.php

@@ -20,9 +20,20 @@ class Collection extends ImmutableCollection implements ICollection {
     /**
      * @inheritDoc
      */
-    public function add ($value): self {
+    public function merge (IImmutableCollection ...$collections): ICollection {
-        $this->elements[] = $value;
+        return $this->_merge(...$collections);
-        return $this;
+    }
+    /**
+     * @inheritDoc
+     */
+    public function add (...$values): self {
+        return $this->_add(...$values);
+    }
+    /**
+     * @inheritDoc
+     */
+    public function addCollection (IImmutableCollection ...$collections): ICollection {
+        return $this->_addCollection(...$collections);
     }
 
     /**

src/Collections/ICollection.php

@@ -23,15 +23,31 @@ interface ICollection extends IImmutableCollection {
      */
     public function set ($key, $value): self;
     /**
-     * Add a value
+     * Merge one or multiple collections in the current one
      *
-     * @param mixed        $value The value
+     * @param IImmutableCollection ...$collections The collections to merge
      *
-     * @psalm-param TValue $value
+     * @return $this
+     */
+    public function merge (IImmutableCollection ...$collections): self;
+    /**
+     * Add one or multiple values
+     *
+     * @param mixed        ...$values The values
+     *
+     * @psalm-param TValue ...$values
      *
      * @return $this
      */
-    public function add ($value): self;
+    public function add (...$values): self;
+    /**
+     * Add the <b>values</b> of one or multiple collections
+     *
+     * @param IImmutableCollection ...$collections The collections to add
+     *
+     * @return mixed
+     */
+    public function addCollection (IImmutableCollection ...$collections): self;
 
     /**
      * Empties the collection

src/Collections/IImmutableCollection.php

@@ -158,4 +158,13 @@ interface IImmutableCollection extends IteratorAggregate, JsonSerializable, Seri
      * @return static
      */
     public static function split (string $value, string $separator): self;
+
+    /**
+     * Combine the current collection with one or multiple other collections
+     *
+     * @param IImmutableCollection ...$collections The other collections to combine
+     *
+     * @return static The combine collection
+     */
+    public function combineWith (IImmutableCollection ...$collections): self;
 }

src/Collections/ImmutableCollection.php

@@ -77,19 +77,51 @@ class ImmutableCollection implements IImmutableCollection {
         $this->elements[$this->_normalizeKey($key)] = $value;
         return $this;
     }
+    /**
+     * Internally merge one or multiple collections in the current one
+     *
+     * @param IImmutableCollection ...$collections The collections to merge
+     *
+     * @return $this
+     */
+    protected function _merge (IImmutableCollection ...$collections): self {
+        foreach ($collections as $collection) {
+            foreach ($collection as $key => $value) {
+                $this->_set($key, $value);
+            }
+        }
+        return $this;
+    }
     /**
      * Internally add a value
      *
-     * @param mixed        $value The value
+     * @param mixed        ...$values The value
      *
-     * @psalm-param TValue $value
+     * @psalm-param TValue ...$value
      *
      * @return $this
      * @internal
      *
      */
-    protected function _add ($value): self {
+    protected function _add (...$values): self {
-        $this->elements[] = $value;
+        foreach ($values as $value) {
+            $this->elements[] = $value;
+        }
+        return $this;
+    }
+    /**
+     * Internally add the <b>values</b> of one or multiple collections
+     *
+     * @param IImmutableCollection ...$collections The collections to add
+     *
+     * @return mixed
+     */
+    protected function _addCollection (IImmutableCollection ...$collections): self {
+        foreach ($collections as $collection) {
+            foreach ($collection as $value) {
+                $this->_add($value);
+            }
+        }
         return $this;
     }
     /**
@@ -296,4 +328,11 @@ class ImmutableCollection implements IImmutableCollection {
     public static function split (string $value, string $separator): self {
         return new static (explode($separator, $value));
     }
+
+    /**
+     * @inheritDoc
+     */
+    public function combineWith (IImmutableCollection ...$collections): IImmutableCollection {
+        return (clone $this)->_merge(...$collections);
+    }
 }

tests/test_class.php

@@ -25,8 +25,7 @@ class Measure {
 function getMeasures (): Collection {
     $measures = new Collection();
     $measures->add(new Measure(38));
-    $measures->add(new Measure(27));
+    $measures->add(new Measure(27), new Measure(34));
-    $measures->add(new Measure(34));
 
     return $measures;
 }