diff options
Diffstat (limited to 'vendor/ramsey/collection/src/CollectionInterface.php')
| -rw-r--r-- | vendor/ramsey/collection/src/CollectionInterface.php | 112 |
1 files changed, 80 insertions, 32 deletions
diff --git a/vendor/ramsey/collection/src/CollectionInterface.php b/vendor/ramsey/collection/src/CollectionInterface.php index aa86feb04..e3ad01470 100644 --- a/vendor/ramsey/collection/src/CollectionInterface.php +++ b/vendor/ramsey/collection/src/CollectionInterface.php @@ -14,8 +14,14 @@ declare(strict_types=1); namespace Ramsey\Collection; +use Ramsey\Collection\Exception\CollectionMismatchException; +use Ramsey\Collection\Exception\InvalidArgumentException; +use Ramsey\Collection\Exception\InvalidPropertyOrMethod; +use Ramsey\Collection\Exception\NoSuchElementException; +use Ramsey\Collection\Exception\UnsupportedOperationException; + /** - * A collection represents a group of objects, known as its elements. + * A collection represents a group of values, known as its elements. * * Some collections allow duplicate elements and others do not. Some are ordered * and others unordered. @@ -26,16 +32,6 @@ namespace Ramsey\Collection; interface CollectionInterface extends ArrayInterface { /** - * Ascending sort type. - */ - public const SORT_ASC = 'asc'; - - /** - * Descending sort type. - */ - public const SORT_DESC = 'desc'; - - /** * Ensures that this collection contains the specified element (optional * operation). * @@ -58,9 +54,11 @@ interface CollectionInterface extends ArrayInterface * @param T $element The element to add to the collection. * * @return bool `true` if this collection changed as a result of the call. + * + * @throws InvalidArgumentException if the collection refuses to add the + * $element for any reason other than that it already contains the element. */ - // phpcs:ignore SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint - public function add($element): bool; + public function add(mixed $element): bool; /** * Returns `true` if this collection contains the specified element. @@ -68,8 +66,7 @@ interface CollectionInterface extends ArrayInterface * @param T $element The element to check whether the collection contains. * @param bool $strict Whether to perform a strict type check on the value. */ - // phpcs:ignore SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint - public function contains($element, bool $strict = true): bool; + public function contains(mixed $element, bool $strict = true): bool; /** * Returns the type associated with this collection. @@ -84,15 +81,20 @@ interface CollectionInterface extends ArrayInterface * * @return bool `true` if an element was removed as a result of this call. */ - // phpcs:ignore SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint - public function remove($element): bool; + public function remove(mixed $element): bool; /** - * Returns the values from the given property or method. + * Returns the values from the given property, method, or array key. + * + * @param string $propertyOrMethod The name of the property, method, or + * array key to evaluate and return. * - * @param string $propertyOrMethod The property or method name to filter by. + * @return array<int, mixed> * - * @return list<mixed> + * @throws InvalidPropertyOrMethod if the $propertyOrMethod does not exist + * on the elements in this collection. + * @throws UnsupportedOperationException if unable to call column() on this + * collection. */ public function column(string $propertyOrMethod): array; @@ -100,29 +102,41 @@ interface CollectionInterface extends ArrayInterface * Returns the first item of the collection. * * @return T + * + * @throws NoSuchElementException if this collection is empty. */ - public function first(); + public function first(): mixed; /** * Returns the last item of the collection. * * @return T + * + * @throws NoSuchElementException if this collection is empty. */ - public function last(); + public function last(): mixed; /** - * Sort the collection by a property or method with the given sort order. + * Sort the collection by a property, method, or array key with the given + * sort order. + * + * If $propertyOrMethod is `null`, this will sort by comparing each element. * * This will always leave the original collection untouched and will return * a new one. * - * @param string $propertyOrMethod The property or method to sort by. - * @param string $order The sort order for the resulting collection (one of - * this interface's `SORT_*` constants). + * @param string | null $propertyOrMethod The property, method, or array key + * to sort by. + * @param Sort $order The sort order for the resulting collection. * * @return CollectionInterface<T> + * + * @throws InvalidPropertyOrMethod if the $propertyOrMethod does not exist + * on the elements in this collection. + * @throws UnsupportedOperationException if unable to call sort() on this + * collection. */ - public function sort(string $propertyOrMethod, string $order = self::SORT_ASC): self; + public function sort(?string $propertyOrMethod = null, Sort $order = Sort::Ascending): self; /** * Filter out items of the collection which don't match the criteria of @@ -134,24 +148,31 @@ interface CollectionInterface extends ArrayInterface * See the {@link http://php.net/manual/en/function.array-filter.php PHP array_filter() documentation} * for examples of how the `$callback` parameter works. * - * @param callable(T):bool $callback A callable to use for filtering elements. + * @param callable(T): bool $callback A callable to use for filtering elements. * * @return CollectionInterface<T> */ public function filter(callable $callback): self; /** - * Create a new collection where items match the criteria of given callback. + * Create a new collection where the result of the given property, method, + * or array key of each item in the collection equals the given value. * * This will always leave the original collection untouched and will return * a new one. * - * @param string $propertyOrMethod The property or method to evaluate. + * @param string | null $propertyOrMethod The property, method, or array key + * to evaluate. If `null`, the element itself is compared to $value. * @param mixed $value The value to match. * * @return CollectionInterface<T> + * + * @throws InvalidPropertyOrMethod if the $propertyOrMethod does not exist + * on the elements in this collection. + * @throws UnsupportedOperationException if unable to call where() on this + * collection. */ - public function where(string $propertyOrMethod, $value): self; + public function where(?string $propertyOrMethod, mixed $value): self; /** * Apply a given callback method on each item of the collection. @@ -163,7 +184,7 @@ interface CollectionInterface extends ArrayInterface * See the {@link http://php.net/manual/en/function.array-map.php PHP array_map() documentation} * for examples of how the `$callback` parameter works. * - * @param callable(T):TCallbackReturn $callback A callable to apply to each + * @param callable(T): TCallbackReturn $callback A callable to apply to each * item of the collection. * * @return CollectionInterface<TCallbackReturn> @@ -173,6 +194,23 @@ interface CollectionInterface extends ArrayInterface public function map(callable $callback): self; /** + * Apply a given callback method on each item of the collection + * to reduce it to a single value. + * + * See the {@link http://php.net/manual/en/function.array-reduce.php PHP array_reduce() documentation} + * for examples of how the `$callback` and `$initial` parameters work. + * + * @param callable(TCarry, T): TCarry $callback A callable to apply to each + * item of the collection to reduce it to a single value. + * @param TCarry $initial This is the initial value provided to the callback. + * + * @return TCarry + * + * @template TCarry + */ + public function reduce(callable $callback, mixed $initial): mixed; + + /** * Create a new collection with divergent items between current and given * collection. * @@ -180,6 +218,9 @@ interface CollectionInterface extends ArrayInterface * items. * * @return CollectionInterface<T> + * + * @throws CollectionMismatchException if the compared collections are of + * differing types. */ public function diff(CollectionInterface $other): self; @@ -191,6 +232,9 @@ interface CollectionInterface extends ArrayInterface * intersecting items. * * @return CollectionInterface<T> + * + * @throws CollectionMismatchException if the compared collections are of + * differing types. */ public function intersect(CollectionInterface $other): self; @@ -200,6 +244,10 @@ interface CollectionInterface extends ArrayInterface * @param CollectionInterface<T> ...$collections The collections to merge. * * @return CollectionInterface<T> + * + * @throws CollectionMismatchException if unable to merge any of the given + * collections or items within the given collections due to type + * mismatch errors. */ public function merge(CollectionInterface ...$collections): self; } |