feat(collections): introduce Set, SetInterface, MutableSet, and…

… `MutableSetInterface` Signed-off-by: azjezz <azjezz@protonmail.com>
azjezz · Jul 1, 2024 · 6710fc4 · 6710fc4
1 parent cb7bd70
commit 6710fc4
Show file tree

Hide file tree

Showing 9 changed files with 1,892 additions and 181 deletions.
diff --git a/src/Psl/Collection/AccessibleCollectionInterface.php b/src/Psl/Collection/AccessibleCollectionInterface.php
@@ -43,7 +43,7 @@ public function keys(): AccessibleCollectionInterface;
      * that meet a supplied condition.
      *
      * Only values that meet a certain criteria are affected by a call to
-     * `filter()`, while all values are affected by a call to `map()`.
+     * `filter()`.
      *
      * The keys associated with the current `AccessibleCollectionInterface` remain unchanged in the
      * returned `AccessibleCollectionInterface`.
@@ -61,8 +61,7 @@ public function filter(Closure $fn): AccessibleCollectionInterface;
      * that meet a supplied condition applied to its keys and values.
      *
      * Only keys and values that meet a certain criteria are affected by a call
-     * to `filterWithKey()`, while all values are affected by a call to
-     * `mapWithKey()`.
+     * to `filterWithKey()`.
      *
      * The keys associated with the current `AccessibleCollectionInterface` remain unchanged in the
      * returned `AccessibleCollectionInterface`; the keys will be used in the filtering process only.
@@ -76,48 +75,6 @@ public function filter(Closure $fn): AccessibleCollectionInterface;
      */
     public function filterWithKey(Closure $fn): AccessibleCollectionInterface;
 
-    /**
-     * Returns a `AccessibleCollectionInterface` after an operation has been applied to each value
-     * in the current `AccessibleCollectionInterface`.
-     *
-     * Every value in the current Map is affected by a call to `map()`, unlike
-     * `filter()` where only values that meet a certain criteria are affected.
-     *
-     * The keys will remain unchanged from the current `AccessibleCollectionInterface` to the
-     * returned `AccessibleCollectionInterface`.
-     *
-     * @template Tu
-     *
-     * @param (Closure(Tv): Tu) $fn The callback containing the operation to apply to the current
-     *                              `AccessibleCollectionInterface` values.
-     *
-     * @return AccessibleCollectionInterface<Tk, Tu> A `AccessibleCollectionInterface` containing key/value
-     *                                               pairs after a user-specified operation is applied.
-     */
-    public function map(Closure $fn): AccessibleCollectionInterface;
-
-    /**
-     * Returns a `AccessibleCollectionInterface` after an operation has been applied to each key and
-     * value in the current `AccessibleCollectionInterface`.
-     *
-     * Every key and value in the current `AccessibleCollectionInterface` is affected by a call to
-     * `mapWithKey()`, unlike `filterWithKey()` where only values that meet a
-     * certain criteria are affected.
-     *
-     * The keys will remain unchanged from this `AccessibleCollectionInterface` to the returned
-     * `AccessibleCollectionInterface`. The keys are only used to help in the mapping operation.
-     *
-     * @template Tu
-     *
-     * @param (Closure(Tk, Tv): Tu) $fn The callback containing the operation to apply to the current
-     *                                  `AccessibleCollectionInterface` keys and values.
-     *
-     * @return AccessibleCollectionInterface<Tk, Tu> A `AccessibleCollectionInterface` containing the values
-     *                                               after a user-specified operation on the current
-     *                                               `AccessibleCollectionInterface`'s keys and values is  applied.
-     */
-    public function mapWithKey(Closure $fn): AccessibleCollectionInterface;
-
     /**
      * Returns the first value in the current `AccessibleCollectionInterface`.
      *

diff --git a/src/Psl/Collection/CollectionInterface.php b/src/Psl/Collection/CollectionInterface.php
@@ -60,8 +60,7 @@ public function jsonSerialize(): array;
      * Returns a `CollectionInterface` containing the values of the current `CollectionInterface`
      * that meet a supplied condition.
      *
-     * Only values that meet a certain criteria are affected by a call to
-     * `filter()`, while all values are affected by a call to `map()`.
+     * Only values that meet a certain criteria are affected by a call to `filter()`.
      *
      * The keys associated with the current `CollectionInterface` remain unchanged in the
      * returned `CollectionInterface`.
@@ -79,8 +78,7 @@ public function filter(Closure $fn): CollectionInterface;
      * that meet a supplied condition applied to its keys and values.
      *
      * Only keys and values that meet a certain criteria are affected by a call
-     * to `filterWithKey()`, while all values are affected by a call to
-     * `mapWithKey()`.
+     * to `filterWithKey()`.
      *
      * The keys associated with the current `CollectionInterface` remain unchanged in the
      * returned `CollectionInterface`; the keys will be used in the filtering process only.
@@ -94,47 +92,6 @@ public function filter(Closure $fn): CollectionInterface;
      */
     public function filterWithKey(Closure $fn): CollectionInterface;
 
-    /**
-     * Returns a `CollectionInterface` after an operation has been applied to each value
-     * in the current `CollectionInterface`.
-     *
-     * Every value in the current Map is affected by a call to `map()`, unlike
-     * `filter()` where only values that meet a certain criteria are affected.
-     *
-     * The keys will remain unchanged from the current `CollectionInterface` to the
-     * returned `CollectionInterface`.
-     *
-     * @template Tu
-     *
-     * @param (Closure(Tv): Tu) $fn The callback containing the operation to apply to the current
-     *                              `CollectionInterface` values.
-     *
-     * @return CollectionInterface<Tk, Tu> A `CollectionInterface` containing key/value pairs after
-     *                                     a user-specified operation is applied.
-     */
-    public function map(Closure $fn): CollectionInterface;
-
-    /**
-     * Returns a `CollectionInterface` after an operation has been applied to each key and
-     * value in the current `CollectionInterface`.
-     *
-     * Every key and value in the current `CollectionInterface` is affected by a call to
-     * `mapWithKey()`, unlike `filterWithKey()` where only values that meet a
-     * certain criteria are affected.
-     *
-     * The keys will remain unchanged from this `CollectionInterface` to the returned
-     * `CollectionInterface`. The keys are only used to help in the mapping operation.
-     *
-     * @template Tu
-     *
-     * @param (Closure(Tk, Tv): Tu) $fn The callback containing the operation to apply to the current
-     *                                  `CollectionInterface` keys and values.
-     *
-     * @return CollectionInterface<Tk, Tu> A `CollectionInterface` containing the values after a user-specified
-     *                                     operation on the current `CollectionInterface`'s keys and values is applied.
-     */
-    public function mapWithKey(Closure $fn): CollectionInterface;
-
     /**
      * Returns a `CollectionInterface` where each element is a `array{0: Tv, 1: Tu}` that combines the
      * element of the current `CollectionInterface` and the provided elements array.

diff --git a/src/Psl/Collection/Exception/RuntimeException.php b/src/Psl/Collection/Exception/RuntimeException.php
@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Collection\Exception;
+
+use Psl\Exception;
+
+final class RuntimeException extends Exception\RuntimeException implements ExceptionInterface
+{
+}
diff --git a/src/Psl/Collection/MutableAccessibleCollectionInterface.php b/src/Psl/Collection/MutableAccessibleCollectionInterface.php
@@ -49,7 +49,7 @@ public function keys(): MutableAccessibleCollectionInterface;
      * `MutableAccessibleCollectionInterface` that meet a supplied condition.
      *
      * Only values that meet a certain criteria are affected by a call to
-     * `filter()`, while all values are affected by a call to `map()`.
+     * `filter()`.
      *
      * The keys associated with the current `MutableAccessibleCollectionInterface` remain unchanged in the
      * returned `MutableAccessibleCollectionInterface`.
@@ -67,8 +67,7 @@ public function filter(Closure $fn): MutableAccessibleCollectionInterface;
      * `MutableAccessibleCollectionInterface` that meet a supplied condition applied to its keys and values.
      *
      * Only keys and values that meet a certain criteria are affected by a call
-     * to `filterWithKey()`, while all values are affected by a call to
-     * `mapWithKey()`.
+     * to `filterWithKey()`.
      *
      * The keys associated with the current `MutableAccessibleCollectionInterface` remain unchanged in the
      * returned `MutableAccessibleCollectionInterface`; the keys will be used in the filtering process only.
@@ -83,49 +82,6 @@ public function filter(Closure $fn): MutableAccessibleCollectionInterface;
      */
     public function filterWithKey(Closure $fn): MutableAccessibleCollectionInterface;
 
-    /**
-     * Returns a `MutableAccessibleCollectionInterface` after an operation has been applied to each value
-     * in the current `MutableAccessibleCollectionInterface`.
-     *
-     * Every value in the current Map is affected by a call to `map()`, unlike
-     * `filter()` where only values that meet a certain criteria are affected.
-     *
-     * The keys will remain unchanged from the current `MutableAccessibleCollectionInterface` to the
-     * returned `MutableAccessibleCollectionInterface`.
-     *
-     * @template Tu
-     *
-     * @param (Closure(Tv): Tu) $fn The callback containing the operation to apply to the current
-     *                              `MutableAccessibleCollectionInterface` values.
-     *
-     * @return MutableAccessibleCollectionInterface<Tk, Tu> A `MutableAccessibleCollectionInterface` containing
-     *                                                      key/value pairs after a user-specified operation is applied.
-     */
-    public function map(Closure $fn): MutableAccessibleCollectionInterface;
-
-    /**
-     * Returns a `MutableAccessibleCollectionInterface` after an operation has been applied to each key and
-     * value in the current `MutableAccessibleCollectionInterface`.
-     *
-     * Every key and value in the current `MutableAccessibleCollectionInterface` is affected by a call to
-     * `mapWithKey()`, unlike `filterWithKey()` where only values that meet a
-     * certain criteria are affected.
-     *
-     * The keys will remain unchanged from this `MutableAccessibleCollectionInterface` to the returned
-     * `MutableAccessibleCollectionInterface`. The keys are only used to help in the mapping operation.
-     *
-     * @template Tu
-     *
-     * @param (Closure(Tk, Tv): Tu) $fn The callback containing the operation to apply to the current
-     *                                  `MutableAccessibleCollectionInterface` keys and values.
-     *
-     * @return MutableAccessibleCollectionInterface<Tk, Tu> A `MutableAccessibleCollectionInterface` containing
-     *                                                      the values after a user-specified operation on the current
-     *                                                      `MutableAccessibleCollectionInterface`'s keys and values is
-     *                                                      applied.
-     */
-    public function mapWithKey(Closure $fn): MutableAccessibleCollectionInterface;
-
     /**
      * Stores a value into the current collection with the specified key,
      * overwriting the previous value associated with the key.

diff --git a/src/Psl/Collection/MutableCollectionInterface.php b/src/Psl/Collection/MutableCollectionInterface.php
@@ -26,7 +26,7 @@ interface MutableCollectionInterface extends CollectionInterface
      * that meet a supplied condition.
      *
      * Only values that meet a certain criteria are affected by a call to
-     * `filter()`, while all values are affected by a call to `map()`.
+     * `filter()`.
      *
      * The keys associated with the current `MutableCollectionInterface` remain unchanged in the
      * returned `MutableCollectionInterface`.
@@ -44,8 +44,7 @@ public function filter(Closure $fn): MutableCollectionInterface;
      * that meet a supplied condition applied to its keys and values.
      *
      * Only keys and values that meet a certain criteria are affected by a call
-     * to `filterWithKey()`, while all values are affected by a call to
-     * `mapWithKey()`.
+     * to `filterWithKey()`.
      *
      * The keys associated with the current `MutableCollectionInterface` remain unchanged in the
      * returned `MutableCollectionInterface`; the keys will be used in the filtering process only.
@@ -59,48 +58,6 @@ public function filter(Closure $fn): MutableCollectionInterface;
      */
     public function filterWithKey(Closure $fn): MutableCollectionInterface;
 
-    /**
-     * Returns a `MutableCollectionInterface` after an operation has been applied to each value
-     * in the current `MutableCollectionInterface`.
-     *
-     * Every value in the current Map is affected by a call to `map()`, unlike
-     * `filter()` where only values that meet a certain criteria are affected.
-     *
-     * The keys will remain unchanged from the current `MutableCollectionInterface` to the
-     * returned `MutableCollectionInterface`.
-     *
-     * @template Tu
-     *
-     * @param (Closure(Tv): Tu) $fn The callback containing the operation to apply to the current
-     *                              `MutableCollectionInterface` values.
-     *
-     * @return MutableCollectionInterface<Tk, Tu> A `MutableCollectionInterface` containing key/value pairs
-     *                                            after a user-specified operation is applied.
-     */
-    public function map(Closure $fn): MutableCollectionInterface;
-
-    /**
-     * Returns a `MutableCollectionInterface` after an operation has been applied to each key and
-     * value in the current `MutableCollectionInterface`.
-     *
-     * Every key and value in the current `MutableCollectionInterface` is affected by a call to
-     * `mapWithKey()`, unlike `filterWithKey()` where only values that meet a
-     * certain criteria are affected.
-     *
-     * The keys will remain unchanged from this `MutableCollectionInterface` to the returned
-     * `MutableCollectionInterface`. The keys are only used to help in the mapping operation.
-     *
-     * @template Tu
-     *
-     * @param (Closure(Tk, Tv): Tu) $fn The callback containing the operation to apply to the current
-     *                                  `MutableCollectionInterface` keys and values.
-     *
-     * @return MutableCollectionInterface<Tk, Tu> A `MutableCollectionInterface` containing the values
-     *                                            after a user-specified operation on the current
-     *                                            `MutableCollectionInterface`'s keys and values is applied.
-     */
-    public function mapWithKey(Closure $fn): MutableCollectionInterface;
-
     /**
      * Returns a `MutableCollectionInterface` where each element is a `array{0: Tv, 1: Tu}` that combines the
      * element of the current `MutableCollectionInterface` and the provided elements.