From f4a1c7e5f3bf1b84beae6e7cadb1695ac790b0e5 Mon Sep 17 00:00:00 2001 From: Sebastian Meyer Date: Mon, 12 Feb 2024 17:20:45 +0100 Subject: [PATCH] Update phpDoc for DataStructures --- src/DataStructures/StrictCollection.php | 211 +++++++------ src/DataStructures/StrictList.php | 379 ++++++++++++++++++++---- src/DataStructures/StrictQueue.php | 24 +- src/DataStructures/StrictStack.php | 24 +- 4 files changed, 467 insertions(+), 171 deletions(-) diff --git a/src/DataStructures/StrictCollection.php b/src/DataStructures/StrictCollection.php index 51db0cc..96726e5 100644 --- a/src/DataStructures/StrictCollection.php +++ b/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\InterfaceTraits\CountableTrait; +use OCC\Basics\Interfaces\ArrayAccessTrait; +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 * @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 AllowedType $item The new item + * @param array-key $offset The new item's index + * @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)) { - throw new InvalidArgumentException( - sprintf( - 'Parameter 2 must be an allowed type, %s given.', - get_debug_type($item) - ) - ); - } - $this->data[$key] = $item; + $this->offsetSet($offset, $value); } /** @@ -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); - } - - /** - * Magic getter method for $this->allowedTypes. - * - * @return string[] The list of allowed data types - * - * @internal - */ - protected function magicGetAllowedTypes(): array - { - return $this->getAllowedTypes(); + return array_is_list($this->_data); } /** * 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)) { - throw new InvalidArgumentException( - 'Parameter 1 must be an integer or string, NULL given.' - ); - } - if (!$this->isAllowedType($item)) { + if (!is_integer($offset) && !is_string($offset)) { throw new InvalidArgumentException( sprintf( - 'Parameter 2 must be an allowed type, %s given.', - get_debug_type($item) + 'Parameter 1 must be an integer or string, %s given.', + 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 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 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 $items */ + /** @var AllowedType[] $items */ $items = $data['StrictCollection::items']; - foreach ($items as $key => $item) { - $this->add($key, $item); + foreach ($items as $offset => $value) { + $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); - } } diff --git a/src/DataStructures/StrictList.php b/src/DataStructures/StrictList.php index dd4df61..5c3bd4c 100644 --- a/src/DataStructures/StrictList.php +++ b/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 * @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 AllowedType $value The new value for the 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 + * @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)) { - throw new InvalidArgumentException( - sprintf( - 'Parameter 2 must be an allowed type, %s given.', - get_debug_type($value) - ) - ); - } - parent::add($offset, $value); + $this->offsetSet($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 $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 - * @param AllowedType $value The new value for the offset + * @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 * - * @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 $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. - * - * @param AllowedType $value The value to push + * Move the cursor to the previous list index. * * @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 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 = []) { diff --git a/src/DataStructures/StrictQueue.php b/src/DataStructures/StrictQueue.php index 1af7c65..90bbe00 100644 --- a/src/DataStructures/StrictQueue.php +++ b/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 - * the allowed data types for list items. + * Extends [\SplDoublyLinkedList](https://www.php.net/spldoublylinkedlist) with + * 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 * @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 = []) { diff --git a/src/DataStructures/StrictStack.php b/src/DataStructures/StrictStack.php index 10a46e7..00c355c 100644 --- a/src/DataStructures/StrictStack.php +++ b/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 - * the allowed data types for list items. + * Extends [\SplDoublyLinkedList](https://www.php.net/spldoublylinkedlist) with + * 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 * @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 = []) {