Rework datastructures to use trait

src/DataStructures/StrictCollection.php

@@ -27,35 +27,17 @@ use ArrayAccess;
 use Countable;
 use DomainException;
 use InvalidArgumentException;
+use OCC\Basics\DataStructures\Exceptions\InvalidDataTypeException;
 use OCC\Basics\Interfaces\ArrayAccessTrait;
 use OCC\Basics\Interfaces\CountableTrait;
-use OCC\Basics\Traits\Getter;
+use OCC\Basics\Traits\TypeChecker;
+use OutOfRangeException;
 use Serializable;
 
 use function array_is_list;
-use function array_map;
-use function array_sum;
-use function count;
-use function function_exists;
 use function get_debug_type;
-use function is_a;
-use function is_array;
-use function is_bool;
-use function is_callable;
-use function is_countable;
-use function is_double;
-use function is_float;
-use function is_int;
 use function is_integer;
-use function is_iterable;
-use function is_long;
-use function is_null;
-use function is_numeric;
-use function is_resource;
-use function is_scalar;
 use function is_string;
-use function is_object;
-use function ltrim;
 use function serialize;
 use function sprintf;
 use function unserialize;
@@ -73,8 +55,6 @@ use function unserialize;
  * @author Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
  * @package Basics\DataStructures
  *
- * @property-read string[] $allowedTypes The allowed data types for items.
- *
  * @api
  *
  * @template AllowedType of mixed
@@ -86,35 +66,28 @@ class StrictCollection implements ArrayAccess, Countable, Serializable
     use ArrayAccessTrait;
     /** @use CountableTrait<AllowedType> */
     use CountableTrait;
-    use Getter;
+    use TypeChecker {
-
+        setAllowedTypes as protected;
-    /**
+    }
-     * The allowed data types for collection items.
-     *
-     * @var string[]
-     *
-     * @internal
-     */
-    protected array $allowedTypes = [];
 
     /**
      * Holds the collection's items.
      *
-     * @var AllowedType[]
+     * @var array<array-key, AllowedType>
      *
      * @internal
      */
     protected array $_data = [];
 
     /**
-     * Add/insert a new item at the specified index.
+     * Add/insert a item at the specified index.
      *
-     * @param array-key $offset The new item's index
+     * @param array-key $offset The item's index
-     * @param AllowedType $value The new item
+     * @param AllowedType $value The item
      *
      * @return void
      *
-     * @throws InvalidArgumentException if `$offset` is not of allowed type
+     * @throws InvalidDataTypeException if `$value` is not of allowed type
      *
      * @api
      */
@@ -140,53 +113,25 @@ class StrictCollection implements ArrayAccess, Countable, Serializable
      *
      * @param array-key $offset The item's index
      *
-     * @return ?AllowedType The item or NULL if key is invalid
+     * @return AllowedType The item
+     *
+     * @throws OutOfRangeException when `$offset` is out of bounds
      *
      * @api
      */
     public function get(int|string $offset): mixed
     {
-        return $this->offsetGet($offset);
+        if (!$this->offsetExists($offset)) {
-    }
+            throw new OutOfRangeException(
-
+                sprintf(
-    /**
+                    'Offset %s is not a valid index key for this collection.',
-     * Get allowed data types for collection items.
+                    $offset
-     *
+                )
-     * @return string[] The list of allowed data types
+            );
-     *
-     * @api
-     */
-    public function getAllowedTypes(): array
-    {
-        return $this->allowedTypes;
-    }
-
-    /**
-     * Check if the item's data type is allowed in the collection.
-     *
-     * @param AllowedType $value The item to check
-     *
-     * @return bool Whether the item's data type is allowed
-     *
-     * @api
-     */
-    public function isAllowedType(mixed $value): bool
-    {
-        if (count($this->allowedTypes) === 0) {
-            return true;
         }
-        foreach ($this->allowedTypes as $type) {
+        /** @var AllowedType $value */
-            $function = 'is_' . $type;
+        $value = $this->offsetGet($offset);
-            if (function_exists($function) && $function($value)) {
+        return $value;
-                return true;
-            }
-            /** @var class-string $fqcn */
-            $fqcn = ltrim($type, '\\');
-            if (is_object($value) && is_a($value, $fqcn)) {
-                return true;
-            }
-        }
-        return false;
     }
 
     /**
@@ -226,7 +171,8 @@ class StrictCollection implements ArrayAccess, Countable, Serializable
      *
      * @return void
      *
-     * @throws InvalidArgumentException if `$offset` or `$value` is not of allowed type
+     * @throws InvalidDataTypeException if `$value` is not of allowed type
+     * @throws InvalidArgumentException if `$offset` is not a valid array key
      *
      * @api
      */
@@ -240,8 +186,8 @@ class StrictCollection implements ArrayAccess, Countable, Serializable
                 )
             );
         }
-        if (!$this->isAllowedType($value)) {
+        if (!$this->hasAllowedType($value)) {
-            throw new InvalidArgumentException(
+            throw new InvalidDataTypeException(
                 sprintf(
                     'Parameter 2 must be an allowed type, %s given.',
                     get_debug_type($value)
@@ -258,10 +204,20 @@ class StrictCollection implements ArrayAccess, Countable, Serializable
      *
      * @return void
      *
+     * @throws OutOfRangeException when `$offset` is out of bounds
+     *
      * @api
      */
     public function remove(int|string $offset): void
     {
+        if (!$this->offsetExists($offset)) {
+            throw new OutOfRangeException(
+                sprintf(
+                    'Offset %s is not a valid index key for this collection.',
+                    $offset
+                )
+            );
+        }
         $this->offsetUnset($offset);
     }
 
@@ -283,7 +239,7 @@ class StrictCollection implements ArrayAccess, Countable, Serializable
      *
      * @return void
      *
-     * @throws InvalidArgumentException if `$value` is not of allowed type
+     * @throws InvalidDataTypeException if `$value` is not of allowed type
      *
      * @api
      */
@@ -292,29 +248,10 @@ class StrictCollection implements ArrayAccess, Countable, Serializable
         $this->offsetSet($offset, $value);
     }
 
-    /**
-     * Set allowed data types of collection items.
-     *
-     * @param string[] $allowedTypes Allowed data types of items
-     *
-     * @return void
-     *
-     * @throws InvalidArgumentException if any value of `$allowedTypes` is not a string
-     */
-    protected function setAllowedTypes(array $allowedTypes = []): void
-    {
-        if (array_sum(array_map('is_string', $allowedTypes)) !== count($allowedTypes)) {
-            throw new InvalidArgumentException(
-                'Allowed types must be array of strings or empty array.'
-            );
-        }
-        $this->allowedTypes = $allowedTypes;
-    }
-
     /**
      * Return array representation of collection.
      *
-     * @return AllowedType[] Array of collection items
+     * @return array<array-key, AllowedType> Array of collection items
      *
      * @api
      */
@@ -338,12 +275,11 @@ class StrictCollection implements ArrayAccess, Countable, Serializable
     {
         if (!$this->isList()) {
             throw new DomainException(
-                'Cannot convert into list: collection contains non-integer and/or non-consecutive keys.'
+                'Cannot convert into StrictList: collection contains non-integer and/or non-consecutive keys.'
             );
         }
-        $strictList = new StrictList($this->allowedTypes);
+        $strictList = new StrictList($this->getAllowedTypes());
-        $items = $this->toArray();
+        $strictList->append(...$this->toArray());
-        $strictList->append(...$items);
         return $strictList;
     }
 
@@ -361,18 +297,6 @@ class StrictCollection implements ArrayAccess, Countable, Serializable
         $this->__unserialize($dataArray);
     }
 
-    /**
-     * Magic getter method for $this->allowedTypes.
-     *
-     * @return string[] The list of allowed data types
-     *
-     * @internal
-     */
-    protected function _magicGetAllowedTypes(): array
-    {
-        return $this->getAllowedTypes();
-    }
-
     /**
      * Create a type-sensitive collection of items.
      *
@@ -425,8 +349,8 @@ class StrictCollection implements ArrayAccess, Countable, Serializable
     public function __serialize(): array
     {
         return [
-            'StrictCollection::allowedTypes' => $this->allowedTypes,
+            'StrictCollection::allowedTypes' => $this->getAllowedTypes(),
-            'StrictCollection::items' => $this->_data
+            'StrictCollection::items' => $this->toArray()
         ];
     }
 
@@ -446,7 +370,7 @@ class StrictCollection implements ArrayAccess, Countable, Serializable
         /** @var string[] $allowedTypes */
         $allowedTypes = $data['StrictCollection::allowedTypes'];
         $this->setAllowedTypes($allowedTypes);
-        /** @var AllowedType[] $items */
+        /** @var array<array-key, AllowedType> $items */
         $items = $data['StrictCollection::items'];
         foreach ($items as $offset => $value) {
             $this->offsetSet($offset, $value);

src/DataStructures/StrictList.php

@@ -23,46 +23,8 @@ declare(strict_types=1);
 
 namespace OCC\Basics\DataStructures;
 
-use ArrayAccess;
+use OCC\Basics\DataStructures\Traits\StrictSplDatastructureTrait;
-use Countable;
-use InvalidArgumentException;
-use Iterator;
-use OutOfRangeException;
-use RangeException;
-use RuntimeException;
 use SplDoublyLinkedList;
-use OCC\Basics\Traits\Getter;
-use Serializable;
-
-use function array_map;
-use function array_sum;
-use function count;
-use function function_exists;
-use function get_debug_type;
-use function in_array;
-use function is_a;
-use function is_array;
-use function is_bool;
-use function is_callable;
-use function is_countable;
-use function is_double;
-use function is_float;
-use function is_int;
-use function is_integer;
-use function is_iterable;
-use function is_long;
-use function is_null;
-use function is_numeric;
-use function is_resource;
-use function is_scalar;
-use function is_string;
-use function is_object;
-use function iterator_to_array;
-use function ltrim;
-use function range;
-use function serialize;
-use function sprintf;
-use function unserialize;
 
 /**
  * A type-sensitive, taversable list.
@@ -74,709 +36,13 @@ use function unserialize;
  * @author Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
  * @package Basics\DataStructures
  *
- * @property-read string[] $allowedTypes The allowed data types for values.
- *
  * @api
  *
  * @template AllowedType of mixed
  * @extends SplDoublyLinkedList<AllowedType>
- * @implements ArrayAccess<int, AllowedType>
- * @implements Iterator<AllowedType>
  */
-class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable, Iterator, Serializable
+class StrictList extends SplDoublyLinkedList
 {
-    use Getter;
+    /** @use StrictSplDatastructureTrait<AllowedType> */
-
+    use StrictSplDatastructureTrait;
-    /**
-     * The allowed data types for list items.
-     *
-     * @var string[]
-     *
-     * @internal
-     */
-    protected array $allowedTypes = [];
-
-    /**
-     * Add/insert a new item at the specified offset.
-     *
-     * @param int $offset The offset where the new item is to be inserted
-     * @param AllowedType $value The new item for the offset
-     *
-     * @return void
-     *
-     * @throws InvalidArgumentException if `$value` is not of allowed type
-     * @throws OutOfRangeException when `$offset` is out of bounds
-     *
-     * @api
-     */
-    public function add(int $offset, mixed $value): void
-    {
-        $this->offsetSet($offset, $value);
-    }
-
-    /**
-     * Append items at the end of the list.
-     *
-     * @param AllowedType ...$values One or more items to append
-     *
-     * @return void
-     *
-     * @throws InvalidArgumentException if any `$values` is not of allowed type
-     *
-     * @api
-     */
-    public function append(mixed ...$values): void
-    {
-        /** @var array<int, AllowedType> $values */
-        foreach ($values as $count => $value) {
-            if (!$this->isAllowedType($value)) {
-                throw new InvalidArgumentException(
-                    sprintf(
-                        'Parameter %d must be an allowed type, %s given.',
-                        $count + 1,
-                        get_debug_type($value)
-                    )
-                );
-            }
-        }
-        foreach ($values as $value) {
-            parent::push($value);
-        }
-    }
-
-    /**
-     * Peek at the item at the beginning of the list.
-     *
-     * @return AllowedType The first item of the list
-     *
-     * @throws RuntimeException if the list is empty
-     *
-     * @api
-     */
-    public function bottom(): mixed
-    {
-        return parent::bottom();
-    }
-
-    /**
-     * Clear the list of any items.
-     *
-     * @return void
-     *
-     * @api
-     */
-    public function clear(): void
-    {
-        while (!$this->isEmpty()) {
-            $this->pop();
-        }
-        $this->rewind();
-    }
-
-    /**
-     * Get the number of items on the list.
-     *
-     * @return int The number of items on the list
-     *
-     * @api
-     */
-    public function count(): int
-    {
-        return parent::count();
-    }
-
-    /**
-     * Get the current list item.
-     *
-     * @return AllowedType The current item
-     *
-     * @api
-     */
-    public function current(): mixed
-    {
-        return parent::current();
-    }
-
-    /**
-     * Get the item at the specified index.
-     *
-     * @param int $offset The item's index
-     *
-     * @return AllowedType The item
-     *
-     * @throws OutOfRangeException when `$offset` is out of bounds
-     *
-     * @api
-     */
-    public function get(int $offset): mixed
-    {
-        return $this->offsetGet($offset);
-    }
-
-    /**
-     * Get allowed data types for list items.
-     *
-     * @return string[] The list of allowed data types
-     *
-     * @api
-     */
-    public function getAllowedTypes(): array
-    {
-        return $this->allowedTypes;
-    }
-
-    /**
-     * Get the mode of iteration.
-     *
-     * @return int The set of flags and modes of iteration
-     *
-     * @api
-     */
-    public function getIteratorMode(): int
-    {
-        return parent::getIteratorMode();
-    }
-
-    /**
-     * Check if the item's data type is allowed on the list.
-     *
-     * @param AllowedType $value The item to check
-     *
-     * @return bool Whether the item's data type is allowed
-     *
-     * @api
-     */
-    public function isAllowedType(mixed $value): bool
-    {
-        if (count($this->allowedTypes) === 0) {
-            return true;
-        }
-        foreach ($this->allowedTypes as $type) {
-            $function = 'is_' . $type;
-            if (function_exists($function) && $function($value)) {
-                return true;
-            }
-            /** @var class-string $fqcn */
-            $fqcn = ltrim($type, '\\');
-            if (is_object($value) && is_a($value, $fqcn)) {
-                return true;
-            }
-        }
-        return false;
-    }
-
-    /**
-     * Check if list is empty.
-     *
-     * @return bool Whether the list contains no items
-     *
-     * @api
-     */
-    public function isEmpty(): bool
-    {
-        return parent::isEmpty();
-    }
-
-    /**
-     * Check if this can be considered a list.
-     *
-     * @return true Always TRUE (this exists only for compatibility reasons)
-     *
-     * @api
-     */
-    public function isList(): bool
-    {
-        return true;
-    }
-
-    /**
-     * Get the current list index.
-     *
-     * @return int The current list index
-     *
-     * @api
-     */
-    public function key(): int
-    {
-        return parent::key();
-    }
-
-    /**
-     * Move the cursor to the next list index.
-     *
-     * @return void
-     *
-     * @api
-     */
-    public function next(): void
-    {
-        parent::next();
-    }
-
-    /**
-     * Check if the specified index exists and is not empty.
-     *
-     * @param int $offset The index to check
-     *
-     * @return bool Whether the index exists and is not empty
-     *
-     * @api
-     */
-    public function offsetExists(mixed $offset): bool
-    {
-        return parent::offsetExists($offset);
-    }
-
-    /**
-     * Get the item from the specified index.
-     *
-     * @param int $offset The item's index
-     *
-     * @return AllowedType The item
-     *
-     * @throws OutOfRangeException when `$offset` is out of bounds
-     *
-     * @api
-     */
-    public function offsetGet(mixed $offset): mixed
-    {
-        return parent::offsetGet($offset);
-    }
-
-    /**
-     * Set the item at the specified offset.
-     *
-     * @param ?int $offset The offset being set or NULL to append
-     * @param AllowedType $value The new item for the offset
-     *
-     * @return void
-     *
-     * @throws InvalidArgumentException if `$value` is not of allowed type
-     * @throws OutOfRangeException when `$offset` is out of bounds
-     *
-     * @api
-     */
-    public function offsetSet(mixed $offset, mixed $value): void
-    {
-        if (!$this->isAllowedType($value)) {
-            throw new InvalidArgumentException(
-                sprintf(
-                    'Parameter 2 must be an allowed type, %s given.',
-                    get_debug_type($value)
-                )
-            );
-        }
-        /** @psalm-suppress PossiblyNullArgument */
-        parent::offsetSet($offset, $value);
-    }
-
-    /**
-     * Unset the item at the specified index.
-     *
-     * @param int $offset The item's index
-     *
-     * @return void
-     *
-     * @throws OutOfRangeException when `$offset` is out of bounds
-     *
-     * @api
-     */
-    public function offsetUnset(mixed $offset): void
-    {
-        parent::offsetUnset($offset);
-    }
-
-    /**
-     * Pops an item from the end of the list.
-     *
-     * @return AllowedType The item from the end of the list
-     *
-     * @throws RuntimeException if the list is empty
-     *
-     * @api
-     */
-    public function pop(): mixed
-    {
-        return parent::pop();
-    }
-
-    /**
-     * Prepend items at the start of the list.
-     *
-     * @param AllowedType ...$values One or more items to prepend
-     *
-     * @return void
-     *
-     * @throws InvalidArgumentException if `$value` is not of allowed type
-     *
-     * @api
-     */
-    public function prepend(mixed ...$values): void
-    {
-        /** @var array<int, AllowedType> $values */
-        foreach ($values as $count => $value) {
-            if (!$this->isAllowedType($value)) {
-                throw new InvalidArgumentException(
-                    sprintf(
-                        'Parameter %d must be an allowed type, %s given.',
-                        $count + 1,
-                        get_debug_type($value)
-                    )
-                );
-            }
-        }
-        foreach ($values as $value) {
-            parent::unshift($value);
-        }
-    }
-
-    /**
-     * Move the cursor to the previous list index.
-     *
-     * @return void
-     *
-     * @api
-     */
-    public function prev(): void
-    {
-        parent::prev();
-    }
-
-    /**
-     * Push an item at the end of the list.
-     *
-     * @param AllowedType $value The item to push
-     *
-     * @return void
-     *
-     * @throws InvalidArgumentException if `$value` is not of allowed type
-     *
-     * @api
-     */
-    public function push(mixed $value): void
-    {
-        if (!$this->isAllowedType($value)) {
-            throw new InvalidArgumentException(
-                sprintf(
-                    'Parameter 1 must be an allowed type, %s given.',
-                    get_debug_type($value)
-                )
-            );
-        }
-        parent::push($value);
-    }
-
-    /**
-     * Remove an item from the list.
-     *
-     * @param int $offset The item's index
-     *
-     * @return void
-     *
-     * @throws OutOfRangeException when `$offset` is out of bounds
-     *
-     * @api
-     */
-    public function remove(int $offset): void
-    {
-        $this->offsetUnset($offset);
-    }
-
-    /**
-     * Rewind the iterator's cursor.
-     *
-     * @return void
-     *
-     * @api
-     */
-    public function rewind(): void
-    {
-        parent::rewind();
-    }
-
-    /**
-     * Get string representation of $this.
-     *
-     * @return string The string representation
-     *
-     * @internal
-     */
-    public function serialize(): string
-    {
-        return serialize($this->__serialize());
-    }
-
-    /**
-     * Set an item at the specified index.
-     *
-     * @param int $offset The item's index
-     * @param AllowedType $value The item
-     *
-     * @return void
-     *
-     * @throws InvalidArgumentException if `$value` is not of allowed type
-     *
-     * @api
-     */
-    public function set(int $offset, mixed $value): void
-    {
-        $this->offsetSet($offset, $value);
-    }
-
-    /**
-     * Set allowed data types of list items.
-     *
-     * @param string[] $allowedTypes Allowed data types of items
-     *
-     * @return void
-     *
-     * @throws InvalidArgumentException if any value of `$allowedTypes` is not a string
-     */
-    protected function setAllowedTypes(array $allowedTypes = []): void
-    {
-        if (array_sum(array_map('is_string', $allowedTypes)) !== count($allowedTypes)) {
-            throw new InvalidArgumentException(
-                'Allowed types must be array of strings or empty array.'
-            );
-        }
-        $this->allowedTypes = $allowedTypes;
-    }
-
-    /**
-     * Set the mode of iteration.
-     *
-     * @param int $mode The new iterator mode (0, 1, 2 or 3)
-     *
-     *                  There are two orthogonal sets of modes that can be set.
-     *
-     *                  The direction of iteration (either one or the other):
-     *                  - StrictList::IT_MODE_FIFO (queue style)
-     *                  - StrictList::IT_MODE_LIFO (stack style)
-     *
-     *                  The behavior of the iterator (either one or the other):
-     *                  - StrictList::IT_MODE_DELETE (delete items)
-     *                  - StrictList::IT_MODE_KEEP (keep items)
-     *
-     *                  The default mode is: IT_MODE_FIFO | IT_MODE_KEEP
-     *
-     * @return int The set of flags and modes of iteration
-     *
-     * @throws RangeException if an invalid `$mode` is given
-     *
-     * @api
-     */
-    public function setIteratorMode(int $mode): int
-    {
-        if (!in_array($mode, range(0, 3), true)) {
-            throw new RangeException(
-                sprintf(
-                    'Iterator mode must be an integer in range [0..3], %d given.',
-                    $mode
-                )
-            );
-        }
-        return parent::setIteratorMode($mode);
-    }
-
-    /**
-     * Shift an item from the beginning of the list.
-     *
-     * @return AllowedType The first item of the list
-     *
-     * @throws RuntimeException if the list is empty
-     *
-     * @api
-     */
-    public function shift(): mixed
-    {
-        return parent::shift();
-    }
-
-    /**
-     * Return array representation of list.
-     *
-     * @return AllowedType[] Array of list items
-     *
-     * @api
-     */
-    public function toArray(): array
-    {
-        return iterator_to_array($this, true);
-    }
-
-    /**
-     * Turn list into a type-sensitive collection.
-     *
-     * @return StrictCollection<AllowedType> A type-sensitive collection of the list's items
-     *
-     * @api
-     */
-    public function toStrictCollection(): StrictCollection
-    {
-        $strictCollection = new StrictCollection($this->allowedTypes);
-        foreach ($this->toArray() as $offset => $value) {
-            $strictCollection[$offset] = $value;
-        }
-        return $strictCollection;
-    }
-
-    /**
-     * Peek at the item at the end of the list.
-     *
-     * @return AllowedType The last item of the list
-     *
-     * @throws RuntimeException if the list is empty
-     *
-     * @api
-     */
-    public function top(): mixed
-    {
-        return parent::top();
-    }
-
-    /**
-     * Restore $this from string representation.
-     *
-     * @param string $data The string representation
-     *
-     * @return void
-     *
-     * @internal
-     */
-    public function unserialize($data): void
-    {
-        /** @var mixed[] $dataArray */
-        $dataArray = unserialize($data);
-        $this->__unserialize($dataArray);
-    }
-
-    /**
-     * Prepend the list with an item.
-     *
-     * @param AllowedType $value The item to unshift
-     *
-     * @return void
-     *
-     * @throws InvalidArgumentException if `$value` is not of allowed type
-     *
-     * @api
-     */
-    public function unshift(mixed $value): void
-    {
-        if (!$this->isAllowedType($value)) {
-            throw new InvalidArgumentException(
-                sprintf(
-                    'Parameter 1 must be an allowed type, %s given.',
-                    get_debug_type($value)
-                )
-            );
-        }
-        parent::unshift($value);
-    }
-
-    /**
-     * Check if current cursor position is valid.
-     *
-     * @return bool Whether the current cursor position is valid
-     *
-     * @api
-     */
-    public function valid(): bool
-    {
-        return parent::valid();
-    }
-
-    /**
-     * Magic getter method for $this->allowedTypes.
-     *
-     * @return string[] The list of allowed data types
-     *
-     * @internal
-     */
-    protected function _magicGetAllowedTypes(): array
-    {
-        return $this->getAllowedTypes();
-    }
-
-    /**
-     * Create a type-sensitive, traversable list of items.
-     *
-     * @param string[] $allowedTypes Allowed data types of items (optional)
-     *
-     *                               If empty, all types are allowed.
-     *                               Possible values are:
-     *                               - "array"
-     *                               - "bool"
-     *                               - "callable"
-     *                               - "countable"
-     *                               - "float" or "double"
-     *                               - "int" or "integer" or "long"
-     *                               - "iterable"
-     *                               - "null"
-     *                               - "numeric"
-     *                               - "object" or FQCN
-     *                               - "resource"
-     *                               - "scalar"
-     *                               - "string"
-     *
-     * @return void
-     *
-     * @throws InvalidArgumentException if any value of `$allowedTypes` is not a string
-     */
-    public function __construct(array $allowedTypes = [])
-    {
-        $this->setAllowedTypes($allowedTypes);
-    }
-
-    /**
-     * Get debug information for $this.
-     *
-     * @return mixed[] The debug information
-     *
-     * @internal
-     */
-    public function __debugInfo(): array
-    {
-        return $this->__serialize();
-    }
-
-    /**
-     * Get array representation of $this.
-     *
-     * @return mixed[] The array representation
-     *
-     * @internal
-     */
-    public function __serialize(): array
-    {
-        return [
-            'StrictList::allowedTypes' => $this->allowedTypes,
-            'SplDoublyLinkedList::dllist' => iterator_to_array($this),
-            'SplDoublyLinkedList::flags' => $this->getIteratorMode()
-        ];
-    }
-
-    /**
-     * Restore $this from array representation.
-     *
-     * @param mixed[] $data The array representation
-     *
-     * @return void
-     *
-     * @internal
-     *
-     * @psalm-suppress MethodSignatureMismatch
-     */
-    public function __unserialize(array $data): void
-    {
-        /** @var string[] $allowedTypes */
-        $allowedTypes = $data['StrictList::allowedTypes'];
-        $this->setAllowedTypes($allowedTypes);
-        /** @var array<int, AllowedType> $values */
-        $values = $data['SplDoublyLinkedList::dllist'];
-        $this->append(...$values);
-        /** @var int $flags */
-        $flags = $data['SplDoublyLinkedList::flags'];
-        $this->setIteratorMode($flags);
-    }
 }

src/DataStructures/StrictQueue.php

@@ -23,24 +23,16 @@ declare(strict_types=1);
 
 namespace OCC\Basics\DataStructures;
 
-use ArrayAccess;
+use OCC\Basics\DataStructures\Exceptions\InvalidDataTypeException;
-use Countable;
+use OCC\Basics\DataStructures\Traits\StrictSplDatastructureTrait;
-use InvalidArgumentException;
+use SplQueue;
-use Iterator;
-use RangeException;
-use RuntimeException;
-use Serializable;
-
-use function sprintf;
 
 /**
  * A type-sensitive, taversable queue (FIFO).
  *
- * Extends [\SplDoublyLinkedList](https://www.php.net/spldoublylinkedlist) with
+ * Extends [\SplQueue](https://www.php.net/splqueue) with an option to restrict
- * an option to restrict the allowed data types for list items by providing the
+ * the allowed data types for list items by providing the constructor with an
- * constructor with an array of atomic types or fully qualified class names. It
+ * array of atomic types or fully qualified class names.
- * also restricts the iterator direction to first-in, first-out (FIFO) exactly
- * like [\SplQueue](https://www.php.net/splqueue).
  *
  * @author Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
  * @package Basics\DataStructures
@@ -48,23 +40,12 @@ use function sprintf;
  * @api
  *
  * @template AllowedType of mixed
- * @extends StrictList<AllowedType>
+ * @extends SplQueue<AllowedType>
- * @implements ArrayAccess<int, AllowedType>
- * @implements Iterator<AllowedType>
  */
-class StrictQueue extends StrictList implements ArrayAccess, Countable, Iterator, Serializable
+class StrictQueue extends SplQueue
 {
-    /**
+    /** @use StrictSplDatastructureTrait<AllowedType> */
-     * Dequeue an item from the queue.
+    use StrictSplDatastructureTrait;
-     *
-     * @return AllowedType The dequeued item
-     *
-     * @api
-     */
-    public function dequeue(): mixed
-    {
-        return parent::shift();
-    }
 
     /**
      * Add an item to the queue.
@@ -73,79 +54,12 @@ class StrictQueue extends StrictList implements ArrayAccess, Countable, Iterator
      *
      * @return void
      *
-     * @throws InvalidArgumentException if `$value` is not of allowed type
+     * @throws InvalidDataTypeException if `$value` is not of allowed type
      *
      * @api
      */
     public function enqueue(mixed $value): void
     {
-        parent::push($value);
+        $this->push($value);
-    }
-
-    /**
-     * Set the mode of iteration.
-     *
-     * @param int $mode The new iterator mode (0 or 1)
-     *
-     *                  There are two orthogonal sets of modes that can be set.
-     *
-     *                  The direction of iteration (fixed for StrictQueue):
-     *                  - StrictQueue::IT_MODE_FIFO (queue style)
-     *
-     *                  The behavior of the iterator (either one or the other):
-     *                  - StrictQueue::IT_MODE_DELETE (delete items)
-     *                  - StrictQueue::IT_MODE_KEEP (keep items)
-     *
-     *                  The default mode is: IT_MODE_FIFO | IT_MODE_KEEP
-     *
-     * @return int The set of flags and modes of iteration
-     *
-     * @throws RangeException if an invalid `$mode` is given
-     * @throws RuntimeException if trying to change iterator direction
-     *
-     * @api
-     */
-    final public function setIteratorMode(int $mode): int
-    {
-        if ($mode > 1) {
-            throw new RuntimeException(
-                sprintf(
-                    'Changing the iterator direction of %s is prohibited.',
-                    static::class
-                )
-            );
-        }
-        return parent::setIteratorMode($mode);
-    }
-
-    /**
-     * Create a type-sensitive, traversable queue of items.
-     *
-     * @param string[] $allowedTypes Allowed data types of items (optional)
-     *
-     *                               If empty, all types are allowed.
-     *                               Possible values are:
-     *                               - "array"
-     *                               - "bool"
-     *                               - "callable"
-     *                               - "countable"
-     *                               - "float" or "double"
-     *                               - "int" or "integer" or "long"
-     *                               - "iterable"
-     *                               - "null"
-     *                               - "numeric"
-     *                               - "object" or FQCN
-     *                               - "resource"
-     *                               - "scalar"
-     *                               - "string"
-     *
-     * @return void
-     *
-     * @throws InvalidArgumentException if any value of `$allowedTypes` is not a string
-     */
-    public function __construct(array $allowedTypes = [])
-    {
-        parent::__construct($allowedTypes);
-        $this->setIteratorMode(0);
     }
 }

src/DataStructures/StrictStack.php

@@ -23,24 +23,17 @@ declare(strict_types=1);
 
 namespace OCC\Basics\DataStructures;
 
-use ArrayAccess;
+use OCC\Basics\DataStructures\Exceptions\InvalidDataTypeException;
-use Countable;
+use OCC\Basics\DataStructures\Traits\StrictSplDatastructureTrait;
-use InvalidArgumentException;
-use Iterator;
-use RangeException;
 use RuntimeException;
-use Serializable;
+use SplStack;
-
-use function sprintf;
 
 /**
  * A type-sensitive, taversable stack (LIFO).
  *
- * Extends [\SplDoublyLinkedList](https://www.php.net/spldoublylinkedlist) with
+ * Extends [\SplStack](https://www.php.net/splstack) with an option to restrict
- * an option to restrict the allowed data types for list items by providing the
+ * the allowed data types for list items by providing the constructor with an
- * constructor with an array of atomic types or fully qualified class names. It
+ * array of atomic types or fully qualified class names.
- * also restricts the iterator direction to last-in, first-out (LIFO) exactly
- * like [\SplStack](https://www.php.net/splstack).
  *
  * @author Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
  * @package Basics\DataStructures
@@ -48,12 +41,13 @@ use function sprintf;
  * @api
  *
  * @template AllowedType of mixed
- * @extends StrictList<AllowedType>
+ * @extends SplStack<AllowedType>
- * @implements ArrayAccess<int, AllowedType>
- * @implements Iterator<AllowedType>
  */
-class StrictStack extends StrictList implements ArrayAccess, Countable, Iterator, Serializable
+class StrictStack extends SplStack
 {
+    /** @use StrictSplDatastructureTrait<AllowedType> */
+    use StrictSplDatastructureTrait;
+
     /**
      * Add an item to the stack.
      *
@@ -61,13 +55,13 @@ class StrictStack extends StrictList implements ArrayAccess, Countable, Iterator
      *
      * @return void
      *
-     * @throws InvalidArgumentException if `$value` is not of allowed type
+     * @throws InvalidDataTypeException if `$value` is not of allowed type
      *
      * @api
      */
     public function stack(mixed $value): void
     {
-        parent::push($value);
+        $this->push($value);
     }
 
     /**
@@ -75,77 +69,12 @@ class StrictStack extends StrictList implements ArrayAccess, Countable, Iterator
      *
      * @return AllowedType The unstacked item
      *
+     * @throws RuntimeException if the list is empty
+     *
      * @api
      */
     public function unstack(): mixed
     {
-        return parent::pop();
+        return $this->pop();
-    }
-
-    /**
-     * Set the mode of iteration.
-     *
-     * @param int $mode The new iterator mode (2 or 3)
-     *
-     *                  There are two orthogonal sets of modes that can be set.
-     *
-     *                  The direction of iteration (fixed for StrictStack):
-     *                  - StrictStack::IT_MODE_LIFO (stack style)
-     *
-     *                  The behavior of the iterator (either one or the other):
-     *                  - StrictStack::IT_MODE_DELETE (delete items)
-     *                  - StrictStack::IT_MODE_KEEP (keep items)
-     *
-     *                  The default mode is: IT_MODE_LIFO | IT_MODE_KEEP
-     *
-     * @return int The set of flags and modes of iteration
-     *
-     * @throws RangeException if an invalid `$mode` is given
-     * @throws RuntimeException if trying to change iterator direction
-     *
-     * @api
-     */
-    final public function setIteratorMode(int $mode): int
-    {
-        if ($mode < 2) {
-            throw new RuntimeException(
-                sprintf(
-                    'Changing the iterator direction of %s is prohibited.',
-                    static::class
-                )
-            );
-        }
-        return parent::setIteratorMode($mode);
-    }
-
-    /**
-     * Create a type-sensitive, traversable stack of items.
-     *
-     * @param string[] $allowedTypes Allowed data types of items (optional)
-     *
-     *                               If empty, all types are allowed.
-     *                               Possible values are:
-     *                               - "array"
-     *                               - "bool"
-     *                               - "callable"
-     *                               - "countable"
-     *                               - "float" or "double"
-     *                               - "int" or "integer" or "long"
-     *                               - "iterable"
-     *                               - "null"
-     *                               - "numeric"
-     *                               - "object" or FQCN
-     *                               - "resource"
-     *                               - "scalar"
-     *                               - "string"
-     *
-     * @return void
-     *
-     * @throws InvalidArgumentException if any value of `$allowedTypes` is not a string
-     */
-    public function __construct(array $allowedTypes = [])
-    {
-        parent::__construct($allowedTypes);
-        $this->setIteratorMode(2);
     }
 }