Merge pull request #31 from quant-php/dev

refactor: findBy() of AbstractList returns null or AbstractList

Author: ThorstenSuckow

src/Quant/Core/AbstractList.php

@@ -103,22 +103,24 @@ public function map(callable $mapFn): static
 
 
     /**
-     * Returns the entry in this list given the callback function.
+     * Returns a new AbstractList containing all the entries for which the callable returned `true`.
+     * Returns null if no matches were found.
      *
      * @param callable $findFn A callback. Return true in the function to indicate a match. First match will
      * be returned. The callback is passed the current entry.
      *
-     * @return ?TValue
+     * @return null|static
      */
-    public function findBy(callable $findFn): mixed
+    public function findBy(callable $findFn): null|static
     {
+        $matches = [];
         foreach ($this->data as $resource) {
             if ($findFn($resource) === true) {
-                return $resource;
+                $matches[] = $resource;
             }
         }
 
-        return null;
+        return count($matches) === 0 ? null : static::make(...$matches);
     }
 
 
@@ -194,7 +196,7 @@ protected function compareItems(mixed $a, mixed $b): bool
      *
      * @throws OutOfBoundsException
      */
-    protected function doInsert(mixed $offset, mixed $value)
+    private function doInsert(mixed $offset, mixed $value)
     {
         if (!is_null($offset) && !is_int($offset)) {
             throw new OutOfBoundsException(
@@ -216,7 +218,7 @@ protected function doInsert(mixed $offset, mixed $value)
      *
      * @throws TypeError
      */
-    protected function assertTypeFor(mixed $value): bool
+    private function assertTypeFor(mixed $value): bool
     {
         $entityType = $this->getType();
 

src/Quant/Core/Tests/AbstractListTest.php

@@ -20,6 +20,8 @@
 use OutOfBoundsException;
 use Quant\Core\Contract\Comparable;
 use Quant\Core\Contract\Equatable;
+use Quant\Core\Tests\Resources\Entity;
+use Quant\Core\Tests\Resources\EntityList;
 use stdClass;
 use PHPUnit\Framework\TestCase;
 use TypeError;
@@ -211,9 +213,11 @@ public function testFindBy(): void
 
         /** @phpstan-ignore-next-line */
         $cb = $mock->findCallback(...);
+
         $this->assertSame(
             $cmpList[1],
-            $abstractList->findBy($cb)
+            /** @phpstan-ignore-next-line */
+            $abstractList->findBy($cb)[0]
         );
     }
 
@@ -361,6 +365,36 @@ public function getType(): string
     }
 
 
+    public function testDocs(): void
+    {
+
+        $listA = new EntityList();
+        $listA[] = new Entity("1");
+        $listA[] = new Entity("1");
+
+        $listB = new EntityList();
+        $listB[] = new Entity("1");
+        $listB[] = new Entity("2");
+
+        $this->assertFalse($listA->equals($listB));
+
+        $listC = EntityList::make(new Entity("3"), new Entity("4"));
+
+        $this->assertTrue($listC->map(fn(Entity $item): Entity => $item->setValue("1"))->equals($listA));
+
+        /**
+         * @var Entity $head
+         */
+        $head = $listB->peek();
+        $this->assertSame("2", $head->getValue());
+
+        $this->assertNull($listC->findBy(fn (Entity $item): bool => $item->getValue() === "a"));
+        $this->assertEquals(
+            $listC->findBy(fn (Entity $item): bool => $item->getValue() !== "a")?->toArray(),
+            [$listC[0], $listC[1]]
+        );
+    }
+
 
 // ---------------------
 //    Helper Functions

src/Quant/Core/Tests/Resources/Entity.php

@@ -0,0 +1,28 @@
+<?php
+
+/**
+ * This file is part of the quant project.
+ *
+ * (c) 2023 Thorsten Suckow-Homberg <[email protected]>
+ *
+ * For full copyright and license information, please consult the LICENSE-file distributed
+ * with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Quant\Core\Tests\Resources;
+
+use Quant\Core\Attribute\Getter;
+use Quant\Core\Attribute\Setter;
+use Quant\Core\Trait\AccessorTrait;
+
+#[Getter] #[Setter]
+class Entity
+{
+    use AccessorTrait;
+
+    public function __construct(private string $value)
+    {
+    }
+}

src/Quant/Core/Tests/Resources/EntityList.php

@@ -0,0 +1,41 @@
+<?php
+
+/**
+ * This file is part of the quant project.
+ *
+ * (c) 2023 Thorsten Suckow-Homberg <[email protected]>
+ *
+ * For full copyright and license information, please consult the LICENSE-file distributed
+ * with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Quant\Core\Tests\Resources;
+
+use Quant\Core\AbstractList;
+use stdClass;
+
+/**
+ * @extends AbstractList<Entity>
+ */
+class EntityList extends AbstractList
+{
+    public function getType(): string
+    {
+        return Entity::class;
+    }
+
+    protected function compareItems(mixed $a, mixed $b): bool
+    {
+        if (!($a instanceof Entity) && !($b instanceof Entity)) {
+            return false;
+        }
+
+        /**
+         * @var Entity $a
+         * @var Entity $b
+         */
+        return $a->getValue() === $b->getValue();
+    }
+}