Update phpDoc for DataStructures

src/DataStructures/StrictCollection.php

@@ -25,15 +25,23 @@ namespace OCC\Basics\DataStructures;
 
 use ArrayAccess;
 use Countable;
+use DomainException;
 use InvalidArgumentException;
-use OCC\Basics\InterfaceTraits\ArrayAccessTrait;
+use OCC\Basics\Interfaces\ArrayAccessTrait;
-use OCC\Basics\InterfaceTraits\CountableTrait;
+use OCC\Basics\Interfaces\CountableTrait;
 use OCC\Basics\Traits\Getter;
 use Serializable;
 
 /**
  * A type-sensitive, unsorted collection.
  *
+ * Holds items as key/value pairs where keys have to be valid array keys while
+ * values can be of any type. To restrict allowed data types for items, provide
+ * the constructor with an array of atomic types or fully qualified class
+ * names.
+ *
+ * Internally it holds the items in the protected `$_data` array.
+ *
  * @author Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
  * @package Basics\DataStructures
  *
@@ -61,29 +69,30 @@ class StrictCollection implements ArrayAccess, Countable, Serializable
      */
     protected array $allowedTypes = [];
 
+    /**
+     * Holds the collection's items.
+     *
+     * @var AllowedType[]
+     *
+     * @internal
+     */
+    protected array $_data = [];
+
     /**
      * Add/insert a new item at the specified index.
      *
-     * @param array-key $key The new item's index
+     * @param array-key $offset The new item's index
-     * @param AllowedType $item The new item
+     * @param AllowedType $value The new item
      *
      * @return void
      *
-     * @throws InvalidArgumentException
+     * @throws InvalidArgumentException if `$offset` is not of allowed type
      *
      * @api
      */
-    public function add(int|string $key, mixed $item): void
+    public function add(int|string $offset, mixed $value): void
     {
-        if (!$this->isAllowedType($item)) {
+        $this->offsetSet($offset, $value);
-            throw new InvalidArgumentException(
-                sprintf(
-                    'Parameter 2 must be an allowed type, %s given.',
-                    get_debug_type($item)
-                )
-            );
-        }
-        $this->data[$key] = $item;
     }
 
     /**
@@ -95,21 +104,21 @@ class StrictCollection implements ArrayAccess, Countable, Serializable
      */
     public function clear(): void
     {
-        $this->data = [];
+        $this->_data = [];
     }
 
     /**
      * Get the item at the specified index.
      *
-     * @param array-key $key The item's index
+     * @param array-key $offset The item's index
      *
      * @return ?AllowedType The item or NULL if key is invalid
      *
      * @api
      */
-    public function get(int|string $key): mixed
+    public function get(int|string $offset): mixed
     {
-        return $this->data[$key] ?? null;
+        return $this->offsetGet($offset);
     }
 
     /**
@@ -127,25 +136,25 @@ class StrictCollection implements ArrayAccess, Countable, Serializable
     /**
      * Check if the item's data type is allowed in the collection.
      *
-     * @param AllowedType $item The item to check
+     * @param AllowedType $value The item to check
      *
      * @return bool Whether the item's data type is allowed
      *
      * @api
      */
-    public function isAllowedType(mixed $item): bool
+    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($item)) {
+            if (function_exists($function) && $function($value)) {
                 return true;
             }
             /** @var class-string $fqcn */
             $fqcn = ltrim($type, '\\');
-            if (is_object($item) && is_a($item, $fqcn)) {
+            if (is_object($value) && is_a($value, $fqcn)) {
                 return true;
             }
         }
@@ -155,7 +164,7 @@ class StrictCollection implements ArrayAccess, Countable, Serializable
     /**
      * Check if collection is empty.
      *
-     * @return bool Whether the collection contains any items
+     * @return bool Whether the collection contains no items
      *
      * @api
      */
@@ -167,83 +176,94 @@ class StrictCollection implements ArrayAccess, Countable, Serializable
     /**
      * Check if this collection can be considered a list.
      *
+     * It is considered a list if all keys are consecutive integers starting
+     * from `0`.
+     *
      * @return bool Whether the collection is a list
      *
      * @api
+     *
+     * @see StrictCollection::toStrictList()
      */
     public function isList(): bool
     {
-        return array_is_list($this->data);
+        return array_is_list($this->_data);
-    }
-
-    /**
-     * Magic getter method for $this->allowedTypes.
-     *
-     * @return string[] The list of allowed data types
-     *
-     * @internal
-     */
-    protected function magicGetAllowedTypes(): array
-    {
-        return $this->getAllowedTypes();
     }
 
     /**
      * Set the item at the specified offset.
      *
      * @param ?array-key $offset The offset being set
-     * @param AllowedType $item The new item for the offset
+     * @param AllowedType $value The new item for the offset
      *
      * @return void
      *
-     * @throws InvalidArgumentException
+     * @throws InvalidArgumentException if `$offset` or `$value` is not of allowed type
      *
-     * @internal
+     * @api
      */
-    public function offsetSet(mixed $offset, mixed $item): void
+    public function offsetSet(mixed $offset, mixed $value): void
     {
-        if (is_null($offset)) {
+        if (!is_integer($offset) && !is_string($offset)) {
-            throw new InvalidArgumentException(
-                'Parameter 1 must be an integer or string, NULL given.'
-            );
-        }
-        if (!$this->isAllowedType($item)) {
             throw new InvalidArgumentException(
                 sprintf(
-                    'Parameter 2 must be an allowed type, %s given.',
+                    'Parameter 1 must be an integer or string, %s given.',
-                    get_debug_type($item)
+                    get_debug_type($offset)
                 )
             );
         }
-        $this->add($offset, $item);
+        if (!$this->isAllowedType($value)) {
+            throw new InvalidArgumentException(
+                sprintf(
+                    'Parameter 2 must be an allowed type, %s given.',
+                    get_debug_type($value)
+                )
+            );
+        }
+        $this->_data[$offset] = $value;
     }
 
     /**
      * Remove an item from the collection.
      *
-     * @param array-key $key The item's key
+     * @param array-key $offset The item's key
      *
      * @return void
      *
      * @api
      */
-    public function remove(int|string $key): void
+    public function remove(int|string $offset): void
     {
-        unset($this->data[$key]);
+        $this->offsetUnset($offset);
     }
 
     /**
      * 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 array-key $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|string $offset, mixed $value): void
+    {
+        $this->offsetSet($offset, $value);
+    }
+
     /**
      * Set allowed data types of collection items.
      *
@@ -251,7 +271,7 @@ class StrictCollection implements ArrayAccess, Countable, Serializable
      *
      * @return void
      *
-     * @throws InvalidArgumentException
+     * @throws InvalidArgumentException if any value of `$allowedTypes` is not a string
      */
     protected function setAllowedTypes(array $allowedTypes = []): void
     {
@@ -266,13 +286,37 @@ class StrictCollection implements ArrayAccess, Countable, Serializable
     /**
      * Return array representation of collection.
      *
-     * @return array<AllowedType> Array of collection items
+     * @return AllowedType[] Array of collection items
      *
      * @api
      */
     public function toArray(): array
     {
-        return $this->data;
+        return $this->_data;
+    }
+
+    /**
+     * Turn collection into a type-sensitive list.
+     *
+     * @return StrictList<AllowedType> A type-sensitive list of the collection's items
+     *
+     * @throws DomainException if the collection is not a list
+     *
+     * @api
+     *
+     * @see StrictCollection::isList()
+     */
+    public function toStrictList(): StrictList
+    {
+        if (!$this->isList()) {
+            throw new DomainException(
+                'Cannot convert into list: collection contains non-integer and/or non-consecutive keys.'
+            );
+        }
+        $strictList = new StrictList($this->allowedTypes);
+        $items = $this->toArray();
+        $strictList->append(...$items);
+        return $strictList;
     }
 
     /**
@@ -281,8 +325,6 @@ class StrictCollection implements ArrayAccess, Countable, Serializable
      * @param string $data The string representation
      *
      * @return void
-     *
-     * @internal
      */
     public function unserialize($data): void
     {
@@ -291,6 +333,18 @@ 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.
      *
@@ -314,7 +368,7 @@ class StrictCollection implements ArrayAccess, Countable, Serializable
      *
      * @return void
      *
-     * @throws InvalidArgumentException
+     * @throws InvalidArgumentException if any value of `$allowedTypes` is not a string
      */
     public function __construct(array $allowedTypes = [])
     {
@@ -344,7 +398,7 @@ class StrictCollection implements ArrayAccess, Countable, Serializable
     {
         return [
             'StrictCollection::allowedTypes' => $this->allowedTypes,
-            'StrictCollection::items' => $this->data
+            'StrictCollection::items' => $this->_data
         ];
     }
 
@@ -357,42 +411,17 @@ class StrictCollection implements ArrayAccess, Countable, Serializable
      *
      * @internal
      *
-     * @psalm-suppress MethodSignatureMismatch
+     * @hpsalm-suppress MethodSignatureMismatch
      */
     public function __unserialize(array $data): void
     {
         /** @var string[] $allowedTypes */
         $allowedTypes = $data['StrictCollection::allowedTypes'];
         $this->setAllowedTypes($allowedTypes);
-        /** @var array<AllowedType> $items */
+        /** @var AllowedType[] $items */
         $items = $data['StrictCollection::items'];
-        foreach ($items as $key => $item) {
+        foreach ($items as $offset => $value) {
-            $this->add($key, $item);
+            $this->offsetSet($offset, $value);
         }
     }
-
-    /**
-     * Magic method to read collection items as properties.
-     *
-     * @param array-key $key The item's index
-     *
-     * @return ?AllowedType The item or NULL if key is invalid
-     */
-    public function __get(int|string $key): mixed
-    {
-        return $this->get($key);
-    }
-
-    /**
-     * Magic method to write collection items as properties.
-     *
-     * @param array-key $key The new item's index
-     * @param AllowedType $item The new item
-     *
-     * @return void
-     */
-    public function __set(int|string $key, mixed $item): void
-    {
-        $this->add($key, $item);
-    }
 }

src/DataStructures/StrictList.php

@@ -27,6 +27,8 @@ use ArrayAccess;
 use Countable;
 use InvalidArgumentException;
 use Iterator;
+use OutOfRangeException;
+use RangeException;
 use RuntimeException;
 use SplDoublyLinkedList;
 use OCC\Basics\Traits\Getter;
@@ -36,7 +38,8 @@ use Serializable;
  * A type-sensitive, taversable list.
  *
  * Extends [\SplDoublyLinkedList](https://www.php.net/spldoublylinkedlist) with
- * an option to specify the allowed data types for list values.
+ * an option to restrict the allowed data types for list items by providing the
+ * constructor with an array of atomic types or fully qualified class names.
  *
  * @author Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
  * @package Basics\DataStructures
@@ -55,7 +58,7 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
     use Getter;
 
     /**
-     * The allowed data types for list values.
+     * The allowed data types for list items.
      *
      * @var string[]
      *
@@ -64,49 +67,43 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
     protected array $allowedTypes = [];
 
     /**
-     * Add/insert a new value at the specified offset.
+     * Add/insert a new item at the specified offset.
      *
-     * @param int $offset The offset where the new value is to be inserted
+     * @param int $offset The offset where the new item is to be inserted
-     * @param AllowedType $value The new value for the offset
+     * @param AllowedType $value The new item for the offset
      *
      * @return void
      *
-     * @throws InvalidArgumentException
+     * @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
     {
-        if (!$this->isAllowedType($value)) {
+        $this->offsetSet($offset, $value);
-            throw new InvalidArgumentException(
-                sprintf(
-                    'Parameter 2 must be an allowed type, %s given.',
-                    get_debug_type($value)
-                )
-            );
-        }
-        parent::add($offset, $value);
     }
 
     /**
-     * Append values at the end of the list.
+     * Append items at the end of the list.
      *
-     * @param AllowedType ...$values One or more values to append
+     * @param AllowedType ...$values One or more items to append
      *
      * @return void
      *
-     * @throws InvalidArgumentException
+     * @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.',
-                        (int) $count + 1,
+                        $count + 1,
                         get_debug_type($value)
                     )
                 );
@@ -118,11 +115,11 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
     }
 
     /**
-     * Peek at the value at the beginning of the list.
+     * Peek at the item at the beginning of the list.
      *
-     * @return AllowedType The first value of the list
+     * @return AllowedType The first item of the list
      *
-     * @throws RuntimeException
+     * @throws RuntimeException if the list is empty
      *
      * @api
      */
@@ -132,7 +129,62 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
     }
 
     /**
-     * Get allowed data types for list values.
+     * 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
      *
@@ -156,11 +208,11 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
     }
 
     /**
-     * Check if the value's data type is allowed on the list.
+     * Check if the item's data type is allowed on the list.
      *
-     * @param AllowedType $value The value to check
+     * @param AllowedType $value The item to check
      *
-     * @return bool Whether the value's data type is allowed
+     * @return bool Whether the item's data type is allowed
      *
      * @api
      */
@@ -184,28 +236,95 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
     }
 
     /**
-     * Magic getter method for $this->allowedTypes.
+     * Check if list is empty.
      *
-     * @return string[] The list of allowed data types
+     * @return bool Whether the list contains no items
      *
-     * @internal
+     * @api
      */
-    protected function magicGetAllowedTypes(): array
+    public function isEmpty(): bool
     {
-        return $this->getAllowedTypes();
+        return parent::isEmpty();
     }
 
     /**
-     * Set the value at the specified offset.
+     * Check if this can be considered a list.
      *
-     * @param ?int $offset The offset being set or NULL to append
+     * @return true Always TRUE (this exists only for compatibility reasons)
-     * @param AllowedType $value The new value for the offset
+     *
+     * @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
      *
-     * @throws InvalidArgumentException
+     * @api
+     */
+    public function next(): void
+    {
+        parent::next();
+    }
+
+    /**
+     * Check if the specified index exists and is not empty.
      *
-     * @internal
+     * @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
     {
@@ -222,11 +341,27 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
     }
 
     /**
-     * Pops an value from the end of the list.
+     * Unset the item at the specified index.
      *
-     * @return AllowedType The value from the end of the list
+     * @param int $offset The item's index
      *
-     * @throws RuntimeException
+     * @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
      */
@@ -236,24 +371,25 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
     }
 
     /**
-     * Prepend values at the start of the list.
+     * Prepend items at the start of the list.
      *
-     * @param AllowedType ...$values One or more values to prepend
+     * @param AllowedType ...$values One or more items to prepend
      *
      * @return void
      *
-     * @throws InvalidArgumentException
+     * @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.',
-                        (int) $count + 1,
+                        $count + 1,
                         get_debug_type($value)
                     )
                 );
@@ -265,13 +401,25 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
     }
 
     /**
-     * Push an value at the end of the list.
+     * Move the cursor to the previous list index.
-     *
-     * @param AllowedType $value The value to push
      *
      * @return void
      *
-     * @throws InvalidArgumentException
+     * @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
      */
@@ -288,6 +436,34 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
         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.
      *
@@ -301,13 +477,30 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
     }
 
     /**
-     * Set allowed data types of list values.
+     * Set an item at the specified index.
      *
-     * @param string[] $allowedTypes Allowed data types of values
+     * @param int $offset The item's index
+     * @param AllowedType $value The item
      *
      * @return void
      *
-     * @throws InvalidArgumentException
+     * @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
     {
@@ -338,19 +531,29 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
      *
      * @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 value from the beginning of the list.
+     * Shift an item from the beginning of the list.
      *
-     * @return AllowedType The first value of the list
+     * @return AllowedType The first item of the list
      *
-     * @throws RuntimeException
+     * @throws RuntimeException if the list is empty
      *
      * @api
      */
@@ -360,11 +563,39 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
     }
 
     /**
-     * Peek at the value at the end of the list.
+     * Return array representation of list.
      *
-     * @return AllowedType The last value of the list
+     * @return AllowedType[] Array of list items
      *
-     * @throws RuntimeException
+     * @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
      */
@@ -390,13 +621,13 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
     }
 
     /**
-     * Prepend the list with an value.
+     * Prepend the list with an item.
      *
-     * @param AllowedType $value The value to unshift
+     * @param AllowedType $value The item to unshift
      *
      * @return void
      *
-     * @throws InvalidArgumentException
+     * @throws InvalidArgumentException if `$value` is not of allowed type
      *
      * @api
      */
@@ -414,9 +645,33 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
     }
 
     /**
-     * Create a type-sensitive, traversable list of values.
+     * Check if current cursor position is valid.
      *
-     * @param string[] $allowedTypes Allowed data types of values (optional)
+     * @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:
@@ -436,7 +691,7 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
      *
      * @return void
      *
-     * @throws InvalidArgumentException
+     * @throws InvalidArgumentException if any value of `$allowedTypes` is not a string
      */
     public function __construct(array $allowedTypes = [])
     {

src/DataStructures/StrictQueue.php

@@ -25,15 +25,20 @@ namespace OCC\Basics\DataStructures;
 
 use ArrayAccess;
 use Countable;
+use InvalidArgumentException;
 use Iterator;
+use RangeException;
 use RuntimeException;
 use Serializable;
 
 /**
- * A type-sensitive, taversable First In, First Out queue (FIFO).
+ * A type-sensitive, taversable queue (FIFO).
  *
- * Extends [\SplQueue](https://www.php.net/splqueue) with an option to specify
+ * Extends [\SplDoublyLinkedList](https://www.php.net/spldoublylinkedlist) with
- * the allowed data types for list items.
+ * an option to restrict the allowed data types for list items by providing the
+ * constructor with an array of atomic types or fully qualified class names. It
+ * 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
@@ -62,17 +67,17 @@ class StrictQueue extends StrictList implements ArrayAccess, Countable, Iterator
     /**
      * Add an item to the queue.
      *
-     * @param AllowedType $item The item to enqueue
+     * @param AllowedType $value The item to enqueue
      *
      * @return void
      *
-     * @throws \InvalidArgumentException
+     * @throws InvalidArgumentException if `$value` is not of allowed type
      *
      * @api
      */
-    public function enqueue(mixed $item): void
+    public function enqueue(mixed $value): void
     {
-        parent::push($item);
+        parent::push($value);
     }
 
     /**
@@ -93,7 +98,8 @@ class StrictQueue extends StrictList implements ArrayAccess, Countable, Iterator
      *
      * @return int The set of flags and modes of iteration
      *
-     * @throws RuntimeException
+     * @throws RangeException if an invalid `$mode` is given
+     * @throws RuntimeException if trying to change iterator direction
      *
      * @api
      */
@@ -133,7 +139,7 @@ class StrictQueue extends StrictList implements ArrayAccess, Countable, Iterator
      *
      * @return void
      *
-     * @throws \InvalidArgumentException
+     * @throws InvalidArgumentException if any value of `$allowedTypes` is not a string
      */
     public function __construct(array $allowedTypes = [])
     {

src/DataStructures/StrictStack.php

@@ -25,15 +25,20 @@ namespace OCC\Basics\DataStructures;
 
 use ArrayAccess;
 use Countable;
+use InvalidArgumentException;
 use Iterator;
+use RangeException;
 use RuntimeException;
 use Serializable;
 
 /**
- * A type-sensitive, taversable Last In, First Out stack (LIFO).
+ * A type-sensitive, taversable stack (LIFO).
  *
- * Extends [\SplStack](https://www.php.net/splstack) with an option to specify
+ * Extends [\SplDoublyLinkedList](https://www.php.net/spldoublylinkedlist) with
- * the allowed data types for list items.
+ * an option to restrict the allowed data types for list items by providing the
+ * constructor with an array of atomic types or fully qualified class names. It
+ * 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
@@ -50,17 +55,17 @@ class StrictStack extends StrictList implements ArrayAccess, Countable, Iterator
     /**
      * Add an item to the stack.
      *
-     * @param AllowedType $item The item to stack
+     * @param AllowedType $value The item to stack
      *
      * @return void
      *
-     * @throws \InvalidArgumentException
+     * @throws InvalidArgumentException if `$value` is not of allowed type
      *
      * @api
      */
-    public function stack(mixed $item): void
+    public function stack(mixed $value): void
     {
-        parent::push($item);
+        parent::push($value);
     }
 
     /**
@@ -93,7 +98,8 @@ class StrictStack extends StrictList implements ArrayAccess, Countable, Iterator
      *
      * @return int The set of flags and modes of iteration
      *
-     * @throws RuntimeException
+     * @throws RangeException if an invalid `$mode` is given
+     * @throws RuntimeException if trying to change iterator direction
      *
      * @api
      */
@@ -133,7 +139,7 @@ class StrictStack extends StrictList implements ArrayAccess, Countable, Iterator
      *
      * @return void
      *
-     * @throws \InvalidArgumentException
+     * @throws InvalidArgumentException if any value of `$allowedTypes` is not a string
      */
     public function __construct(array $allowedTypes = [])
     {