chore(collection): throw out-of-bounds exception instead of invariant violation for invalid offset

CHANGELOG.md

@@ -41,3 +41,5 @@
 * **BC** - `Psl\Result\ResultInterface` now implements `Psl\Promise\PromiseInterface`
 * **BC** - `Psl\Type\resource('curl')->toString()` now uses PHP built-in resource kind notation ( i.e: `resource (curl)` ) instead of generic notation ( i.e: `resource<curl>` )
 * **BC** - `Psl\Str`, `Psl\Str\Byte`, and `Psl\Str\Grapheme` functions now throw `Psl\Str\Exception\OutOfBoundsException` instead of `Psl\Exception\InvaraintViolationsException` when `$offset` is out-of-bounds.
+* **BC** - `Psl\Collection\IndexAccessInterface::at()` now throw `Psl\Collection\Exception\OutOfBoundsException` instead of `Psl\Exception\InvariantViolationException` if `$k` is out-of-bounds.
+* **BC** - `Psl\Collection\AccessibleCollectionInterface::slice` signature has changed from `slice(int $start, int $length): static` to `slice(int $start, ?int $length = null): static`

docs/component/collection.md

@@ -25,9 +25,9 @@
 
 #### `Classes`
 
-- [Map](./../../src/Psl/Collection/Map.php#L18)
-- [MutableMap](./../../src/Psl/Collection/MutableMap.php#L18)
-- [MutableVector](./../../src/Psl/Collection/MutableVector.php#L17)
-- [Vector](./../../src/Psl/Collection/Vector.php#L17)
+- [Map](./../../src/Psl/Collection/Map.php#L20)
+- [MutableMap](./../../src/Psl/Collection/MutableMap.php#L20)
+- [MutableVector](./../../src/Psl/Collection/MutableVector.php#L19)
+- [Vector](./../../src/Psl/Collection/Vector.php#L19)
 
 

docs/component/dict.md

@@ -16,7 +16,7 @@
 - [count_values](./../../src/Psl/Dict/count_values.php#L22)
 - [diff](./../../src/Psl/Dict/diff.php#L24)
 - [diff_by_key](./../../src/Psl/Dict/diff_by_key.php#L24)
-- [drop](./../../src/Psl/Dict/drop.php#L27)
+- [drop](./../../src/Psl/Dict/drop.php#L23)
 - [drop_while](./../../src/Psl/Dict/drop_while.php#L26)
 - [equal](./../../src/Psl/Dict/equal.php#L19)
 - [filter](./../../src/Psl/Dict/filter.php#L32)
@@ -41,11 +41,11 @@
 - [pull_with_key](./../../src/Psl/Dict/pull_with_key.php#L35)
 - [reindex](./../../src/Psl/Dict/reindex.php#L37)
 - [select_keys](./../../src/Psl/Dict/select_keys.php#L23)
-- [slice](./../../src/Psl/Dict/slice.php#L31)
+- [slice](./../../src/Psl/Dict/slice.php#L27)
 - [sort](./../../src/Psl/Dict/sort.php#L24)
 - [sort_by](./../../src/Psl/Dict/sort_by.php#L24)
 - [sort_by_key](./../../src/Psl/Dict/sort_by_key.php#L24)
-- [take](./../../src/Psl/Dict/take.php#L22)
+- [take](./../../src/Psl/Dict/take.php#L18)
 - [take_while](./../../src/Psl/Dict/take_while.php#L26)
 - [unique](./../../src/Psl/Dict/unique.php#L17)
 - [unique_by](./../../src/Psl/Dict/unique_by.php#L23)

src/Psl/Collection/AccessibleCollectionInterface.php

@@ -202,8 +202,8 @@ public function zip(iterable $iterable): AccessibleCollectionInterface;
      *
      * `$n` is 1-based. So the first element is 1, the second 2, etc.
      *
-     * @param int $n The last element that will be included in the returned
-     *               `AccessibleCollectionInterface`.
+     * @param int<0, max> $n The last element that will be included in the returned
+     *                       `AccessibleCollectionInterface`.
      *
      * @return AccessibleCollectionInterface<Tk, Tv> A `AccessibleCollectionInterface` that is a proper
      *                                               subset of the current `AccessibleCollectionInterface` up
@@ -239,8 +239,8 @@ public function takeWhile(callable $fn): AccessibleCollectionInterface;
      *
      * `$n` is 1-based. So the first element is 1, the second 2, etc.
      *
-     * @param int $n The last element to be skipped; the $n+1 element will be the
-     *               first one in the returned `AccessibleCollectionInterface`.
+     * @param int<0, max> $n The last element to be skipped; the $n+1 element will be the
+     *                       first one in the returned `AccessibleCollectionInterface`.
      *
      * @return AccessibleCollectionInterface<Tk, Tv> A `AccessibleCollectionInterface` that is a proper subset
      *                                               of the current `AccessibleCollectionInterface` containing values
@@ -278,15 +278,15 @@ public function dropWhile(callable $fn): AccessibleCollectionInterface;
      * The returned `AccessibleCollectionInterface` will always be a proper subset of this
      * `AccessibleCollectionInterface`.
      *
-     * @param int $start The starting key of this Vector to begin the returned
-     *                   `AccessibleCollectionInterface`
-     * @param int $length The length of the returned `AccessibleCollectionInterface`
+     * @param int<0, max> $start The starting key of this Vector to begin the returned
+     *                           `AccessibleCollectionInterface`
+     * @param null|int<0, max> $length The length of the returned `AccessibleCollectionInterface`
      *
      * @return AccessibleCollectionInterface<Tk, Tv> A `AccessibleCollectionInterface` that is a proper subset
      *                                               of the current `AccessibleCollectionInterface` starting at `$start`
      *                                               up to but not including the element `$start + $length`.
      *
      * @psalm-mutation-free
      */
-    public function slice(int $start, int $length): AccessibleCollectionInterface;
+    public function slice(int $start, ?int $length = null): AccessibleCollectionInterface;
 }

src/Psl/Collection/CollectionInterface.php

@@ -31,6 +31,8 @@ public function isEmpty(): bool;
      * Get the number of items in the collection.
      *
      * @psalm-mutation-free
+     *
+     * @return int<0, max>
      */
     public function count(): int;
 
@@ -162,8 +164,8 @@ public function zip(iterable $iterable): CollectionInterface;
      *
      * `$n` is 1-based. So the first element is 1, the second 2, etc.
      *
-     * @param int $n The last element that will be included in the returned
-     *               `CollectionInterface`.
+     * @param int<0, max> $n The last element that will be included in the returned
+     *                       `CollectionInterface`.
      *
      * @return CollectionInterface<Tk, Tv> A `CollectionInterface` that is a proper subset of the current
      *                                     `CollectionInterface` up to `n` elements.
@@ -197,8 +199,8 @@ public function takeWhile(callable $fn): CollectionInterface;
      *
      * `$n` is 1-based. So the first element is 1, the second 2, etc.
      *
-     * @param int $n The last element to be skipped; the $n+1 element will be the
-     *               first one in the returned `CollectionInterface`.
+     * @param int<0, max> $n The last element to be skipped; the $n+1 element will be the
+     *                       first one in the returned `CollectionInterface`.
      *
      * @return CollectionInterface<Tk, Tv> A `CollectionInterface` that is a proper subset of the current
      *                                     `CollectionInterface` containing values after the specified `n`-th element.
@@ -234,15 +236,15 @@ public function dropWhile(callable $fn): CollectionInterface;
      * The returned `CollectionInterface` will always be a proper subset of this
      * `CollectionInterface`.
      *
-     * @param int $start The starting key of this Vector to begin the returned
-     *                   `CollectionInterface`.
-     * @param int $length The length of the returned `CollectionInterface`.
+     * @param int<0, max> $start The starting key of this Vector to begin the returned
+     *                           `CollectionInterface`.
+     * @param int<0, max> $length The length of the returned `CollectionInterface`.
      *
      * @return CollectionInterface<Tk, Tv> A `CollectionInterface` that is a proper subset of the current
      *                                     `CollectionInterface` starting at `$start` up to but not including
      *                                     the element `$start + $length`.
      *
      * @psalm-mutation-free
      */
-    public function slice(int $start, int $length): CollectionInterface;
+    public function slice(int $start, ?int $length = null): CollectionInterface;
 }

src/Psl/Collection/Exception/ExceptionInterface.php

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

src/Psl/Collection/Exception/OutOfBoundsException.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Collection\Exception;
+
+use Psl\Exception;
+use Psl\Str;
+
+final class OutOfBoundsException extends Exception\OutOfBoundsException implements ExceptionInterface
+{
+    public static function for(string|int $offset): OutOfBoundsException
+    {
+        return new self(Str\format('Key (%s) was out-of-bounds.', $offset));
+    }
+}

src/Psl/Collection/IndexAccessInterface.php

@@ -17,6 +17,8 @@ interface IndexAccessInterface
      *
      * @param Tk $k
      *
+     * @throws Exception\OutOfBoundsException If $k is out-of-bounds.
+     *
      * @return Tv
      *
      * @psalm-mutation-free

src/Psl/Collection/Map.php

@@ -4,11 +4,13 @@
 
 namespace Psl\Collection;
 
-use Psl;
 use Psl\Dict;
 use Psl\Iter;
 use Psl\Vec;
 
+use function array_key_exists;
+use function count;
+
 /**
  * @template Tk of array-key
  * @template Tv
@@ -153,11 +155,13 @@ public function isEmpty(): bool
      * Get the number of items in the current map.
      *
      * @psalm-mutation-free
+     *
+     * @return int<0, max>
      */
     public function count(): int
     {
-        /** @psalm-suppress ImpureFunctionCall - conditionally pure */
-        return Iter\count($this->elements);
+        /** @var int<0, max> */
+        return count($this->elements);
     }
 
     /**
@@ -189,15 +193,17 @@ public function jsonSerialize(): array
      *
      * @param Tk $k
      *
-     * @throws Psl\Exception\InvariantViolationException If $k is out-of-bounds.
+     * @throws Exception\OutOfBoundsException If $k is out-of-bounds.
      *
      * @return Tv
      *
      * @psalm-mutation-free
      */
     public function at(string|int $k): mixed
     {
-        Psl\invariant($this->contains($k), 'Key (%s) is out-of-bounds.', $k);
+        if (!array_key_exists($k, $this->elements)) {
+            throw Exception\OutOfBoundsException::for($k);
+        }
 
         return $this->elements[$k];
     }
@@ -211,8 +217,7 @@ public function at(string|int $k): mixed
      */
     public function contains(int|string $k): bool
     {
-        /** @psalm-suppress ImpureFunctionCall - conditionally pure */
-        return Iter\contains_key($this->elements, $k);
+        return array_key_exists($k, $this->elements);
     }
 
     /**
@@ -404,10 +409,8 @@ public function zip(iterable $iterable): Map
      *
      * `$n` is 1-based. So the first element is 1, the second 2, etc.
      *
-     * @param int $n The last element that will be included in the returned
-     *               `Map`.
-     *
-     * @throws Psl\Exception\InvariantViolationException If $n is negative.
+     * @param int<0, max> $n The last element that will be included in the returned
+     *                       `Map`.
      *
      * @return Map<Tk, Tv> A `Map` that is a proper subset of the current
      *                     `Map` up to `n` elements.
@@ -447,10 +450,8 @@ public function takeWhile(callable $fn): Map
      *
      * `$n` is 1-based. So the first element is 1, the second 2, etc.
      *
-     * @param int $n The last element to be skipped; the $n+1 element will be the
-     *               first one in the returned `Map`.
-     *
-     * @throws Psl\Exception\InvariantViolationException If $n is negative.
+     * @param int<0, max> $n The last element to be skipped; the $n+1 element will be the
+     *                       first one in the returned `Map`.
      *
      * @return Map<Tk, Tv> A `Map` that is a proper subset of the current
      *                     `Map` containing values after the specified `n`-th element.
@@ -491,11 +492,9 @@ public function dropWhile(callable $fn): Map
      *
      * The returned `Map` will always be a proper subset of this `Map`.
      *
-     * @param int $start The starting key of this Vector to begin the returned
-     *                   `Map`.
-     * @param null|int $length The length of the returned `Map`
-     *
-     * @throws Psl\Exception\InvariantViolationException If $start or $length are negative.
+     * @param int<0, max> $start The starting key of this Vector to begin the returned
+     *                           `Map`.
+     * @param null|int<0, max> $length The length of the returned `Map`
      *
      * @return Map<Tk, Tv> A `Map` that is a proper subset of the current
      *                     `Map` starting at `$start` up to but not including the element `$start + $length`.

src/Psl/Collection/MapInterface.php

@@ -193,8 +193,8 @@ public function zip(iterable $iterable): MapInterface;
      *
      * `$n` is 1-based. So the first element is 1, the second 2, etc.
      *
-     * @param int $n The last element that will be included in the returned
-     *               `MapInterface`.
+     * @param int<0, max> $n The last element that will be included in the returned
+     *                       `MapInterface`.
      *
      * @return MapInterface<Tk, Tv> A `MapInterface` that is a proper subset of the current
      *                              `MapInterface` up to `n` elements.
@@ -228,8 +228,8 @@ public function takeWhile(callable $fn): MapInterface;
      *
      * `$n` is 1-based. So the first element is 1, the second 2, etc.
      *
-     * @param int $n - The last element to be skipped; the $n+1 element will be the
-     *               first one in the returned `MapInterface`.
+     * @param int<0, max> $n The last element to be skipped; the $n+1 element will be the
+     *                       first one in the returned `MapInterface`.
      *
      * @return MapInterface<Tk, Tv> - A `MapInterface` that is a proper subset of the current
      *                              `MapInterface` containing values after the specified `n`-th element.
@@ -265,15 +265,15 @@ public function dropWhile(callable $fn): MapInterface;
      * The returned `MapInterface` will always be a proper subset of this
      * `MapInterface`.
      *
-     * @param int $start The starting key of this Vector to begin the returned
-     *                   `MapInterface`
-     * @param int $length The length of the returned `MapInterface`
+     * @param int<0, max> $start The starting key of this Vector to begin the returned
+     *                           `MapInterface`
+     * @param null|int<0, max> $length The length of the returned `MapInterface`
      *
      * @return MapInterface<Tk, Tv> - A `MapInterface` that is a proper subset of the current
      *                              `MapInterface` starting at `$start` up to but not including
      *                              the element `$start + $length`.
      *
      * @psalm-mutation-free
      */
-    public function slice(int $start, int $length): MapInterface;
+    public function slice(int $start, ?int $length = null): MapInterface;
 }

src/Psl/Collection/MutableAccessibleCollectionInterface.php

@@ -212,7 +212,7 @@ public function zip(iterable $iterable): MutableAccessibleCollectionInterface;
      *
      * `$n` is 1-based. So the first element is 1, the second 2, etc.
      *
-     * @param int $n The last element that will be included in the returned `MutableAccessibleCollectionInterface`.
+     * @param int<0, max> $n The last element that will be included in the returned `MutableAccessibleCollectionInterface`.
      *
      * @return MutableAccessibleCollectionInterface<Tk, Tv> A `MutableAccessibleCollectionInterface` that is a proper
      *                                                      subset of the current `MutableAccessibleCollectionInterface`
@@ -248,8 +248,8 @@ public function takeWhile(callable $fn): MutableAccessibleCollectionInterface;
      *
      * `$n` is 1-based. So the first element is 1, the second 2, etc.
      *
-     * @param int $n The last element to be skipped; the $n+1 element will be the
-     *               first one in the returned `MutableAccessibleCollectionInterface`.
+     * @param int<0, max> $n The last element to be skipped; the $n+1 element will be the
+     *                       first one in the returned `MutableAccessibleCollectionInterface`.
      *
      * @return MutableAccessibleCollectionInterface<Tk, Tv> A `MutableAccessibleCollectionInterface` that is a proper
      *                                                      subset of the current `MutableAccessibleCollectionInterface`
@@ -287,8 +287,8 @@ public function dropWhile(callable $fn): MutableAccessibleCollectionInterface;
      * The returned `MutableAccessibleCollectionInterface` will always be a proper subset of this
      * `MutableAccessibleCollectionInterface`.
      *
-     * @param int $start The starting key of this Vector to begin the returned `MutableAccessibleCollectionInterface`
-     * @param int $length The length of the returned `MutableAccessibleCollectionInterface`
+     * @param int<0, max> $start The starting key of this Vector to begin the returned `MutableAccessibleCollectionInterface`
+     * @param null|int<0, max> $length The length of the returned `MutableAccessibleCollectionInterface`
      *
      * @return MutableAccessibleCollectionInterface<Tk, Tv> A `MutableAccessibleCollectionInterface` that is a proper
      *                                                      subset of the current `MutableAccessibleCollectionInterface`
@@ -297,5 +297,5 @@ public function dropWhile(callable $fn): MutableAccessibleCollectionInterface;
      *
      * @psalm-mutation-free
      */
-    public function slice(int $start, int $length): MutableAccessibleCollectionInterface;
+    public function slice(int $start, ?int $length = null): MutableAccessibleCollectionInterface;
 }

src/Psl/Collection/MutableCollectionInterface.php

@@ -131,7 +131,7 @@ public function zip(iterable $iterable): MutableCollectionInterface;
      *
      * `$n` is 1-based. So the first element is 1, the second 2, etc.
      *
-     * @param int $n The last element that will be included in the returned `MutableCollectionInterface`.
+     * @param int<0, max> $n The last element that will be included in the returned `MutableCollectionInterface`.
      *
      * @return MutableCollectionInterface<Tk, Tv> A `MutableCollectionInterface` that is a proper
      *                                            subset of the current `MutableCollectionInterface` up to `n` elements.
@@ -166,8 +166,8 @@ public function takeWhile(callable $fn): MutableCollectionInterface;
      *
      * `$n` is 1-based. So the first element is 1, the second 2, etc.
      *
-     * @param int $n - The last element to be skipped; the $n+1 element will be the
-     *               first one in the returned `MutableCollectionInterface`.
+     * @param int<0, max> $n The last element to be skipped; the $n+1 element will be the
+     *                       first one in the returned `MutableCollectionInterface`.
      *
      * @return MutableCollectionInterface<Tk, Tv> A `MutableCollectionInterface` that is a proper
      *                                            subset of the current `MutableCollectionInterface` containing values
@@ -205,17 +205,17 @@ public function dropWhile(callable $fn): MutableCollectionInterface;
      * The returned `MutableCollectionInterface` will always be a proper subset of this
      * `MutableCollectionInterface`.
      *
-     * @param int $start The starting key of this Vector to begin the returned
-     *                   `MutableCollectionInterface`.
-     * @param int $length The length of the returned `MutableCollectionInterface`.
+     * @param int<0, max> $start The starting key of this Vector to begin the returned
+     *                           `MutableCollectionInterface`.
+     * @param null|int<0, max> $length The length of the returned `MutableCollectionInterface`.
      *
      * @return MutableCollectionInterface<Tk, Tv> A `MutableCollectionInterface` that is a proper
      *                                            subset of the current `MutableCollectionInterface` starting
      *                                            at `$start` up to but not including the element `$start + $length`.
      *
      * @psalm-mutation-free
      */
-    public function slice(int $start, int $length): MutableCollectionInterface;
+    public function slice(int $start, ?int $length = null): MutableCollectionInterface;
 
     /**
      * Removes all items from the collection.