Update phpDoc for DataStructures
This commit is contained in:
Sebastian Meyer
parent
c0e8a2b59a
commit
f4a1c7e5f3
|
|
@ -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 <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 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<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) {
|
||||
$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);
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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 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<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
|
||||
* @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<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.
|
||||
*
|
||||
* @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<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 = [])
|
||||
{
|
||||
|
|
|
|||
|
|
@ -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 <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 = [])
|
||||
{
|
||||
|
|
|
|||
|
|
@ -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 <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 = [])
|
||||
{
|
||||
|
|
|
|||
Loading…
Reference in New Issue