From 8b4f09dd73d873e2594a9dc105b2693517e5d47c Mon Sep 17 00:00:00 2001 From: Smoren Date: Tue, 12 Mar 2024 19:55:38 +0300 Subject: [PATCH] PHPdoc, strict types added. --- src/Exceptions/IndexError.php | 2 + src/Exceptions/KeyError.php | 2 + src/Exceptions/NotSupportedError.php | 2 + src/Exceptions/ReadonlyError.php | 2 + src/Exceptions/SizeError.php | 2 + src/Exceptions/ValueError.php | 2 + src/Interfaces/ArrayViewInterface.php | 97 ++++++++++++++++++++------- src/Selectors/IndexListSelector.php | 2 + src/Selectors/MaskSelector.php | 2 + src/Selectors/SliceSelector.php | 2 + src/Structs/NormalizedSlice.php | 2 + src/Structs/Slice.php | 2 + src/Traits/ArrayViewAccessTrait.php | 2 + src/Util.php | 2 + src/Views/ArrayIndexListView.php | 2 + src/Views/ArrayMaskView.php | 2 + src/Views/ArraySliceView.php | 2 + 17 files changed, 106 insertions(+), 23 deletions(-) diff --git a/src/Exceptions/IndexError.php b/src/Exceptions/IndexError.php index 2590f24..0180147 100644 --- a/src/Exceptions/IndexError.php +++ b/src/Exceptions/IndexError.php @@ -1,5 +1,7 @@ > * @extends \IteratorAggregate */ interface ArrayViewInterface extends \ArrayAccess, \IteratorAggregate, \Countable { /** - * @param array|ArrayViewInterface $source - * @param bool|null $readonly - * @return ArrayViewInterface + * Creates an ArrayView instance from the given source array or ArrayView. + * + * * If the source is not an ArrayView, a new ArrayView is created with the provided source. + * * If the source is an ArrayView and the `readonly` parameter is specified as `true`, + * a new readonly ArrayView is created. + * * If the source is an ArrayView and it is already readonly, the same ArrayView is returned. + * + * @param array|ArrayViewInterface $source The source array or ArrayView to create a view from. + * @param bool|null $readonly Optional flag to indicate whether the view should be readonly. + * + * @return ArrayViewInterface An ArrayView instance based on the source array or ArrayView. */ public static function toView(&$source, ?bool $readonly = null): ArrayViewInterface; /** - * @param array|ArrayViewInterface $source - * @param bool|null $readonly - * @return ArrayViewInterface + * Creates an unlinked from source ArrayView instance from the given source array or ArrayView. + * + * * If the source is not an ArrayView, a new ArrayView is created with the provided source. + * * If the source is an ArrayView and the `readonly` parameter is specified as `true`, + * a new readonly ArrayView is created. + * * If the source is an ArrayView and it is already readonly, the same ArrayView is returned. + * + * @param array|ArrayViewInterface $source The source array or ArrayView to create a view from. + * @param bool|null $readonly Optional flag to indicate whether the view should be readonly. + * + * @return ArrayViewInterface An ArrayView instance based on the source array or ArrayView. */ public static function toUnlinkedView($source, ?bool $readonly = null): ArrayViewInterface; /** - * @return array + * Returns the array representation of the view. + * + * @return array The array representation of the view. */ public function toArray(): array; /** - * @param callable(T): bool $predicate - * @return ArrayViewInterface + * Filters the elements in the view based on a predicate function. + * + * @param callable(T): bool $predicate Function that returns a boolean value for each element. + * + * @return ArrayViewInterface A new view with elements that satisfy the predicate. */ public function filter(callable $predicate): ArrayViewInterface; /** - * @param callable(T): bool $predicate - * @return MaskSelectorInterface + * Checks if all elements in the view satisfy a given predicate function. + * + * @param callable(T): bool $predicate Function that returns a boolean value for each element. + * + * @return MaskSelectorInterface Boolean mask for selecting elements that satisfy the predicate. */ public function is(callable $predicate): MaskSelectorInterface; /** - * @param ArraySelectorInterface|string $selector - * @param bool|null $readonly - * @return ArrayViewInterface + * Returns a subview of this view based on a selector or string slice. + * + * @param ArraySelectorInterface|string $selector The selector or string to filter the subview. + * @param bool|null $readonly Flag indicating if the subview should be read-only. + * + * @return ArrayViewInterface A new view representing the subview of this view. */ public function subview($selector, bool $readonly = null): ArrayViewInterface; /** - * @param callable(T, int): T $mapper + * Applies a transformation function to each element in the view. + * + * @param callable(T, int): T $mapper Function to transform each element. * - * @return ArrayViewInterface + * @return ArrayViewInterface this view. */ public function apply(callable $mapper): self; /** - * @template U + * Applies a transformation function using another array or view as rhs values for a binary operation. + * + * @template U The type rhs of a binary operation. * - * @param array|ArrayViewInterface $data - * @param callable(T, U, int): T $mapper + * @param array|ArrayViewInterface $data The rhs values for a binary operation. + * @param callable(T, U, int): T $mapper Function to transform each pair of elements. * - * @return ArrayViewInterface + * @return ArrayViewInterface this view. */ public function applyWith($data, callable $mapper): self; /** - * @param array|ArrayViewInterface|T $newValues + * Sets new values for the elements in the view. * - * @return ArrayViewInterface + * @param array|ArrayViewInterface|T $newValues The new values to set. + * + * @return ArrayViewInterface this view. */ public function set($newValues): self; /** + * Return true if view is readonly, otherwise false. + * * @return bool */ public function isReadonly(): bool; /** + * Return size of the view. + * * @return int */ public function count(): int; @@ -87,6 +128,8 @@ public function count(): int; * @param numeric|string|ArraySelectorInterface $offset * * @return bool + * + * {@inheritDoc} */ public function offsetExists($offset): bool; @@ -94,6 +137,8 @@ public function offsetExists($offset): bool; * @param numeric|string|ArraySelectorInterface $offset * * @return T|array + * + * {@inheritDoc} */ #[\ReturnTypeWillChange] public function offsetGet($offset); @@ -103,6 +148,8 @@ public function offsetGet($offset); * @param T|array|ArrayViewInterface $value * * @return void + * + * {@inheritDoc} */ public function offsetSet($offset, $value): void; @@ -110,10 +157,14 @@ public function offsetSet($offset, $value): void; * @param numeric|string|ArraySelectorInterface $offset * * @return void + * + * {@inheritDoc} */ public function offsetUnset($offset): void; /** + * Return iterator to iterate the view elements. + * * @return \Generator */ public function getIterator(): \Generator; diff --git a/src/Selectors/IndexListSelector.php b/src/Selectors/IndexListSelector.php index 22ffeb7..7b9c037 100644 --- a/src/Selectors/IndexListSelector.php +++ b/src/Selectors/IndexListSelector.php @@ -1,5 +1,7 @@