Merge pull request #6 from boesing/qa/out-of-bounds-exception-in-favo…

…r-of-null

src/ArrayInterface.php

@@ -6,6 +6,7 @@
 
 use Countable;
 use IteratorAggregate;
+use OutOfBoundsException;
 
 /**
  * @internal
@@ -23,14 +24,16 @@ interface ArrayInterface extends IteratorAggregate, Countable
     public function contains($element): bool;
 
     /**
-     * @psalm-return TValue|null
+     * @psalm-return TValue
      * @psalm-mutation-free
+     * @throws OutOfBoundsException if there are no values available.
      */
     public function first();
 
     /**
-     * @psalm-return TValue|null
+     * @psalm-return TValue
      * @psalm-mutation-free
+     * @throws OutOfBoundsException if there are no values available.
      */
     public function last();
 

src/Array_.php

@@ -6,6 +6,7 @@
 
 use ArrayIterator;
 use DateTimeInterface;
+use OutOfBoundsException;
 use Traversable;
 use Webmozart\Assert\Assert;
 
@@ -59,8 +60,8 @@ public function contains($element): bool
      */
     public function first()
     {
-        if ($this->data === []) {
-            return null;
+        if ($this->isEmpty()) {
+            throw new OutOfBoundsException('There are no values available.');
         }
 
         return reset($this->data);
@@ -71,8 +72,8 @@ public function first()
      */
     public function last()
     {
-        if ($this->data === []) {
-            return null;
+        if ($this->isEmpty()) {
+            throw new OutOfBoundsException('There are no values available.');
         }
 
         return end($this->data);

src/Map.php

@@ -4,11 +4,13 @@
 
 namespace Boesing\TypedArrays;
 
+use OutOfBoundsException;
 use Webmozart\Assert\Assert;
 
 use function array_diff_ukey;
 use function array_filter;
 use function array_intersect_ukey;
+use function array_key_exists;
 use function array_keys;
 use function array_map;
 use function array_merge;
@@ -17,6 +19,7 @@
 use function array_uintersect_uassoc;
 use function array_values;
 use function asort;
+use function sprintf;
 use function uasort;
 use function usort;
 
@@ -138,7 +141,11 @@ public function put($key, $value): MapInterface
      */
     public function get($key)
     {
-        return $this->data[$key] ?? null;
+        if (! array_key_exists($key, $this->data)) {
+            throw new OutOfBoundsException(sprintf('There is no value stored for provided key: %s', (string) $key));
+        }
+
+        return $this->data[$key];
     }
 
     public function intersect(MapInterface $other, ?callable $valueComparator = null): MapInterface

src/MapInterface.php

@@ -4,6 +4,8 @@
 
 namespace Boesing\TypedArrays;
 
+use OutOfBoundsException;
+
 /**
  * @template         TValue
  * @template-extends ArrayInterface<string,TValue>
@@ -91,7 +93,8 @@ public function put($key, $value): MapInterface;
 
     /**
      * @psalm-param string $key
-     * @psalm-return TValue|null
+     * @psalm-return TValue
+     * @throws OutOfBoundsException if key does not exist.
      * @psalm-mutation-free
      */
     public function get($key);

src/OrderedList.php

@@ -11,6 +11,7 @@
 use function array_combine;
 use function array_fill;
 use function array_filter;
+use function array_key_exists;
 use function array_keys;
 use function array_map;
 use function array_merge;
@@ -23,6 +24,7 @@
 use function is_callable;
 use function serialize;
 use function sort;
+use function sprintf;
 use function usort;
 
 use const SORT_NATURAL;
@@ -76,7 +78,11 @@ public function add($element): OrderedListInterface
      */
     public function at(int $position)
     {
-        return $this->data[$position] ?? null;
+        if (! array_key_exists($position, $this->data)) {
+            throw new OutOfBoundsException(sprintf('There is no value stored in that position: %d', $position));
+        }
+
+        return $this->data[$position];
     }
 
     public function sort(?callable $callback = null): OrderedListInterface
@@ -187,7 +193,11 @@ public function unify(
 
         foreach ($instance->data as $value) {
             $identifier = $unificationIdentifierGenerator($value);
-            $unique     = $unified->get($identifier) ?? $value;
+            try {
+                $unique = $unified->get($identifier);
+            } catch (OutOfBoundsException $exception) {
+                $unique = $value;
+            }
 
             if ($callback) {
                 $unique = $callback($unique, $value);

src/OrderedListInterface.php

@@ -20,7 +20,8 @@ interface OrderedListInterface extends ArrayInterface
     public function add($element): OrderedListInterface;
 
     /**
-     * @psalm-return TValue|null
+     * @psalm-return TValue
+     * @throws OutOfBoundsException If position does not exist.
      * @psalm-mutation-free
      */
     public function at(int $position);

tests/GenericMapTest.php

@@ -9,6 +9,7 @@
 use DateTimeImmutable;
 use Generator;
 use Lcobucci\Clock\FrozenClock;
+use OutOfBoundsException;
 use PHPUnit\Framework\TestCase;
 use stdClass;
 
@@ -459,4 +460,11 @@ public function testCanIntersectWithUserFunctions(): void
                 ->toNativeArray()
         );
     }
+
+    public function testGetThrowsOutOfBoundsExceptionWhenKeyDoesNotExist(): void
+    {
+        $map = new GenericMap([]);
+        $this->expectException(OutOfBoundsException::class);
+        $map->get('foo');
+    }
 }

tests/GenericOrderedListTest.php

@@ -202,7 +202,8 @@ public function testReturnsNullWhenSpecificItemNotFound(): void
     {
         $list = new GenericOrderedList([]);
 
-        self::assertNull($list->at(0));
+        $this->expectException(OutOfBoundsException::class);
+        $list->at(0);
     }
 
     /**
@@ -631,11 +632,18 @@ public function testFirstAndLastElementReturnsIdenticalObject(): void
         self::assertEquals($object2, $list->last());
     }
 
-    public function testFirstAndLastReturnNullOnEmptyList(): void
+    public function testFirstThrowsOutOfBoundsExceptionWhenListIsEmpty(): void
     {
         $list = new GenericOrderedList([]);
-        self::assertNull($list->first());
-        self::assertNull($list->last());
+        $this->expectException(OutOfBoundsException::class);
+        $list->first();
+    }
+
+    public function testLastThrowsOutOfBoundsExceptionWhenListIsEmpty(): void
+    {
+        $list = new GenericOrderedList([]);
+        $this->expectException(OutOfBoundsException::class);
+        $list->last();
     }
 
     public function testContainsDoesExactMatch(): void