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

docs/component/collection.md

@@ -16,18 +16,22 @@
 - [CollectionInterface](./../../src/Psl/Collection/CollectionInterface.php#L23)
 - [IndexAccessInterface](./../../src/Psl/Collection/IndexAccessInterface.php#L13)
 - [MapInterface](./../../src/Psl/Collection/MapInterface.php#L15)
-- [MutableAccessibleCollectionInterface](./../../src/Psl/Collection/MutableAccessibleCollectionInterface.php#L22)
+- [MutableAccessibleCollectionInterface](./../../src/Psl/Collection/MutableAccessibleCollectionInterface.php#L23)
 - [MutableCollectionInterface](./../../src/Psl/Collection/MutableCollectionInterface.php#L22)
 - [MutableIndexAccessInterface](./../../src/Psl/Collection/MutableIndexAccessInterface.php#L16)
 - [MutableMapInterface](./../../src/Psl/Collection/MutableMapInterface.php#L16)
+- [MutableSetInterface](./../../src/Psl/Collection/MutableSetInterface.php#L15)
 - [MutableVectorInterface](./../../src/Psl/Collection/MutableVectorInterface.php#L15)
+- [SetInterface](./../../src/Psl/Collection/SetInterface.php#L14)
 - [VectorInterface](./../../src/Psl/Collection/VectorInterface.php#L14)
 
 #### `Classes`
 
 - [Map](./../../src/Psl/Collection/Map.php#L25)
 - [MutableMap](./../../src/Psl/Collection/MutableMap.php#L25)
+- [MutableSet](./../../src/Psl/Collection/MutableSet.php#L22)
 - [MutableVector](./../../src/Psl/Collection/MutableVector.php#L23)
+- [Set](./../../src/Psl/Collection/Set.php#L23)
 - [Vector](./../../src/Psl/Collection/Vector.php#L22)
 
 

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`.
      *

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.

src/Psl/Collection/Exception/InvalidOffsetException.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Collection\Exception;
+
+use Psl\Exception;
+
+final class InvalidOffsetException extends Exception\UnexpectedValueException implements ExceptionInterface
+{
+}

src/Psl/Collection/Exception/OutOfBoundsException.php

@@ -12,7 +12,7 @@ final class OutOfBoundsException extends Exception\OutOfBoundsException implemen
     /**
      * @psalm-mutation-free
      */
-    public static function for(string|int $offset): OutOfBoundsException
+    public static function for(int|string $offset): OutOfBoundsException
     {
         return new self(Str\format('Key (%s) was out-of-bounds.', $offset));
     }

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
+{
+}

src/Psl/Collection/IndexAccessInterface.php

@@ -23,7 +23,7 @@ interface IndexAccessInterface
      *
      * @psalm-mutation-free
      */
-    public function at(string|int $k): mixed;
+    public function at(int|string $k): mixed;
 
     /**
      * Determines if the specified key is in the current collection.
@@ -43,5 +43,5 @@ public function contains(int|string $k): bool;
      *
      * @psalm-mutation-free
      */
-    public function get(string|int $k): mixed;
+    public function get(int|string $k): mixed;
 }

src/Psl/Collection/Map.php

@@ -219,7 +219,7 @@ public function jsonSerialize(): array
      *
      * @psalm-mutation-free
      */
-    public function at(string|int $k): mixed
+    public function at(int|string $k): mixed
     {
         if (!array_key_exists($k, $this->elements)) {
             throw Exception\OutOfBoundsException::for($k);
@@ -249,7 +249,7 @@ public function contains(int|string $k): bool
      *
      * @psalm-mutation-free
      */
-    public function get(string|int $k): mixed
+    public function get(int|string $k): mixed
     {
         return $this->elements[$k] ?? null;
     }