Commaaa2

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.
@@ -25,16 +31,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 property or method name to filter by.
+     * @param string $propertyOrMethod The name of the property, method, or
+     *     array key to evaluate and return.
      *
-     * @return list<mixed>
+     * @return array<int, 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,25 +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.
      */
-    // phpcs:ignore SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint
-    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.
@@ -164,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 +193,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.
@@ -181,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;
 
@@ -192,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;
 
@@ -201,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;
 }