feat: add AbstractList to Core-package

Author: ThorstenSuckow

src/Quant/Core/AbstractList.php

@@ -0,0 +1,325 @@
+<?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;
+
+use ArrayAccess;
+use Quant\Core\Contract\Arrayable;
+use Countable;
+use Iterator;
+use OutOfBoundsException;
+use Quant\Core\Contract\Comparable;
+use Quant\Core\Contract\Equatable;
+use TypeError;
+
+/**
+ * List supporting Generic types.
+ * Each class deriving from AbstractList must provide information about the type maintained
+ * with instances of this list via `getType`.
+ * In addition to the interfaces implemented by this class, additional methods are provided
+ * that help with filtering or looking up entries: #findBy, #peek#, #map
+ *
+ * @template TValue
+ * @implements Iterator<int, TValue>
+ * @implements  ArrayAccess<int, TValue>
+ */
+abstract class AbstractList implements Arrayable, ArrayAccess, Iterator, Countable, Equatable
+{
+    /**
+     * @var array<int, TValue>
+     */
+    protected array $data = [];
+
+    /**
+     * \Iterator Interface
+     * @var int
+     */
+    protected int $position = 0;
+
+
+    /**
+     * Constructor.
+     * Final to allow new static();
+     *
+     * @see make
+     */
+    final public function __construct()
+    {
+    }
+
+
+    /**
+     * Factory method for easily creating instances of the implementing class.
+     *
+     * @param mixed ...$items
+     *
+     * @return static
+     */
+    public static function make(...$items): static
+    {
+        $self = new static();
+
+        foreach ($items as $item) {
+            $self[] = $item;
+        }
+
+        return $self;
+    }
+
+
+    /**
+     * Returns the class name of the entity-type this list should maintain
+     * entries of.
+     *
+     * @return string
+     */
+    abstract public function getType(): string;
+
+
+    /**
+     * Applies the map function to this data and returns **this** list.
+     *
+     * @param callable $mapFn The callable to pass to the callback submitted to
+     * array_map()
+     *
+     * @return static
+     */
+    public function map(callable $mapFn): static
+    {
+        array_map($mapFn, $this->data);
+
+        return $this;
+    }
+
+
+    /**
+     * Returns the entry in this list given the callback function.
+     *
+     * @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
+     */
+    public function findBy(callable $findFn): mixed
+    {
+        foreach ($this->data as $resource) {
+            if ($findFn($resource) === true) {
+                return $resource;
+            }
+        }
+
+        return null;
+    }
+
+
+    /**
+     * Returns the element at the head of the AbstractList, or null if the list is empty.
+     *
+     * @return ?TValue
+     */
+    public function peek(): mixed
+    {
+        $count = count($this->data);
+        return !$count ? null : $this->data[$count - 1];
+    }
+
+
+    public function equals(Equatable $target): bool
+    {
+        $thisClass = get_class($this);
+
+        if (!($target instanceof $thisClass)) {
+            return false;
+        }
+
+        /**
+         * @var AbstractList<TValue> $td
+         */
+        $td = $target->toArray();
+        if (count($td) !== count($this)) {
+            return false;
+        }
+
+        $type = $this->getType();
+        $isEquatable  = is_a($type, Equatable::class, true);
+        $isComparable = is_a($type, Comparable::class, true);
+
+        foreach ($td as $i => $entity) {
+            if ($isEquatable) {
+                if ($entity->equals($this[$i]) === false) {
+                    return false;
+                }
+            } elseif ($isComparable) {
+                if ($entity->compareTo($this[$i]) !== 0) {
+                    return false;
+                }
+            } else {
+                if (!$this->compareItems($this[$i], $entity)) {
+                    return false;
+                }
+            }
+        }
+
+        return true;
+    }
+
+
+    /**
+     * Method called by the abstract list if containing items are neither Equatable nor Comparable.
+     * Override to implement comparator.
+     *
+     * @param mixed $a
+     * @param mixed $b
+     * @return bool
+     */
+    protected function compareItems(mixed $a, mixed $b): bool
+    {
+        return $a === $b;
+    }
+
+    /**
+     * @param mixed $offset
+     * @param mixed $value
+     * @return void
+     *
+     * @throws OutOfBoundsException
+     */
+    protected function doInsert(mixed $offset, mixed $value)
+    {
+        if (!is_null($offset) && !is_int($offset)) {
+            throw new OutOfBoundsException(
+                "expected integer key for \"offset\", " .
+                "but got type: " . (gettype($offset))
+            );
+        }
+
+        if (is_null($offset)) {
+            $this->data[] = $value;
+        } else {
+            $this->data[$offset] = $value;
+        }
+    }
+
+    /**
+     * @param mixed  $value
+     * @return bool
+     *
+     * @throws TypeError
+     */
+    protected function assertTypeFor(mixed $value): bool
+    {
+        $entityType = $this->getType();
+
+        // instanceof has higher precedence, so
+        // (!$value instanceof $entityType)
+        // would also be a valid expression
+        if (!($value instanceof $entityType)) {
+            /** @var object $value */
+            throw new TypeError(
+                "Expected type \"$entityType\" for value-argument, got " . gettype($value)
+            );
+        }
+
+        return true;
+    }
+
+
+// -------------------------
+//  ArrayAccess Interface
+// -------------------------
+
+    /**
+     * @throws TypeError|OutOfBoundsException if $value is not of the type defined
+     * with this getType, or f $offset is not an int
+     */
+    public function offsetSet(mixed $offset, mixed $value): void
+    {
+        $this->assertTypeFor($value);
+        $this->doInsert($offset, $value);
+    }
+
+
+    public function offsetExists($offset): bool
+    {
+        return isset($this->data[$offset]);
+    }
+
+    public function offsetUnset($offset): void
+    {
+        unset($this->data[$offset]);
+    }
+
+
+    public function offsetGet($offset): mixed
+    {
+        return $this->data[$offset] ?? null;
+    }
+
+
+// --------------------------
+//  Iterator Interface
+// --------------------------
+
+    public function rewind(): void
+    {
+        $this->position = 0;
+    }
+
+    public function key(): int
+    {
+        return $this->position;
+    }
+
+    public function current(): mixed
+    {
+        return $this->data[$this->position];
+    }
+
+    public function next(): void
+    {
+        $this->position++;
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function valid(): bool
+    {
+        return isset($this->data[$this->position]);
+    }
+
+// --------------------------
+//  Iterator Interface
+// --------------------------
+
+    /**
+     * @return int
+     */
+    public function count(): int
+    {
+        return count($this->data);
+    }
+
+
+// --------------------------
+//  Arrayable interface
+// --------------------------
+
+    /**
+     * @return array<mixed, TValue>
+     */
+    public function toArray(): array
+    {
+        return $this->data;
+    }
+}