Debian Codegraph @

vendor/ramsey/collection/src/CollectionInterface.php

raw
1 <?php
2
3 /**
4 * This file is part of the ramsey/collection library
5 *
6 * For the full copyright and license information, please view the LICENSE
7 * file that was distributed with this source code.
8 *
9 * @copyright Copyright (c) Ben Ramsey <[email protected]>
10 * @license http://opensource.org/licenses/MIT MIT
11 */
12
13 declare(strict_types=1);
14
15 namespace Ramsey\Collection;
16
17 use Ramsey\Collection\Exception\CollectionMismatchException;
18 use Ramsey\Collection\Exception\InvalidArgumentException;
19 use Ramsey\Collection\Exception\InvalidPropertyOrMethod;
20 use Ramsey\Collection\Exception\NoSuchElementException;
21 use Ramsey\Collection\Exception\UnsupportedOperationException;
22
23 /**
24 * A collection represents a group of values, known as its elements.
25 *
26 * Some collections allow duplicate elements and others do not. Some are ordered
27 * and others unordered.
28 *
29 * @template T
30 * @extends ArrayInterface<T>
31 */
32 interface CollectionInterface extends ArrayInterface
33 {
34 /**
35 * Ensures that this collection contains the specified element (optional
36 * operation).
37 *
38 * Returns `true` if this collection changed as a result of the call.
39 * (Returns `false` if this collection does not permit duplicates and
40 * already contains the specified element.)
41 *
42 * Collections that support this operation may place limitations on what
43 * elements may be added to this collection. In particular, some
44 * collections will refuse to add `null` elements, and others will impose
45 * restrictions on the type of elements that may be added. Collection
46 * classes should clearly specify in their documentation any restrictions
47 * on what elements may be added.
48 *
49 * If a collection refuses to add a particular element for any reason other
50 * than that it already contains the element, it must throw an exception
51 * (rather than returning `false`). This preserves the invariant that a
52 * collection always contains the specified element after this call returns.
53 *
54 * @param T $element The element to add to the collection.
55 *
56 * @return bool `true` if this collection changed as a result of the call.
57 *
58 * @throws InvalidArgumentException if the collection refuses to add the
59 * $element for any reason other than that it already contains the element.
60 */
61 public function add(mixed $element): bool;
62
63 /**
64 * Returns `true` if this collection contains the specified element.
65 *
66 * @param T $element The element to check whether the collection contains.
67 * @param bool $strict Whether to perform a strict type check on the value.
68 */
69 public function contains(mixed $element, bool $strict = true): bool;
70
71 /**
72 * Returns the type associated with this collection.
73 */
74 public function getType(): string;
75
76 /**
77 * Removes a single instance of the specified element from this collection,
78 * if it is present.
79 *
80 * @param T $element The element to remove from the collection.
81 *
82 * @return bool `true` if an element was removed as a result of this call.
83 */
84 public function remove(mixed $element): bool;
85
86 /**
87 * Returns the values from the given property, method, or array key.
88 *
89 * @param string $propertyOrMethod The name of the property, method, or
90 * array key to evaluate and return.
91 *
92 * @return list<mixed>
93 *
94 * @throws InvalidPropertyOrMethod if the $propertyOrMethod does not exist
95 * on the elements in this collection.
96 * @throws UnsupportedOperationException if unable to call column() on this
97 * collection.
98 */
99 public function column(string $propertyOrMethod): array;
100
101 /**
102 * Returns the first item of the collection.
103 *
104 * @return T
105 *
106 * @throws NoSuchElementException if this collection is empty.
107 */
108 public function first(): mixed;
109
110 /**
111 * Returns the last item of the collection.
112 *
113 * @return T
114 *
115 * @throws NoSuchElementException if this collection is empty.
116 */
117 public function last(): mixed;
118
119 /**
120 * Sort the collection by a property, method, or array key with the given
121 * sort order.
122 *
123 * If $propertyOrMethod is `null`, this will sort by comparing each element.
124 *
125 * This will always leave the original collection untouched and will return
126 * a new one.
127 *
128 * @param string | null $propertyOrMethod The property, method, or array key
129 * to sort by.
130 * @param Sort $order The sort order for the resulting collection.
131 *
132 * @return CollectionInterface<T>
133 *
134 * @throws InvalidPropertyOrMethod if the $propertyOrMethod does not exist
135 * on the elements in this collection.
136 * @throws UnsupportedOperationException if unable to call sort() on this
137 * collection.
138 */
139 public function sort(?string $propertyOrMethod = null, Sort $order = Sort::Ascending): self;
140
141 /**
142 * Filter out items of the collection which don't match the criteria of
143 * given callback.
144 *
145 * This will always leave the original collection untouched and will return
146 * a new one.
147 *
148 * See the {@link http://php.net/manual/en/function.array-filter.php PHP array_filter() documentation}
149 * for examples of how the `$callback` parameter works.
150 *
151 * @param callable(T): bool $callback A callable to use for filtering elements.
152 *
153 * @return CollectionInterface<T>
154 */
155 public function filter(callable $callback): self;
156
157 /**
158 * Create a new collection where the result of the given property, method,
159 * or array key of each item in the collection equals the given value.
160 *
161 * This will always leave the original collection untouched and will return
162 * a new one.
163 *
164 * @param string | null $propertyOrMethod The property, method, or array key
165 * to evaluate. If `null`, the element itself is compared to $value.
166 * @param mixed $value The value to match.
167 *
168 * @return CollectionInterface<T>
169 *
170 * @throws InvalidPropertyOrMethod if the $propertyOrMethod does not exist
171 * on the elements in this collection.
172 * @throws UnsupportedOperationException if unable to call where() on this
173 * collection.
174 */
175 public function where(?string $propertyOrMethod, mixed $value): self;
176
177 /**
178 * Apply a given callback method on each item of the collection.
179 *
180 * This will always leave the original collection untouched. The new
181 * collection is created by mapping the callback to each item of the
182 * original collection.
183 *
184 * See the {@link http://php.net/manual/en/function.array-map.php PHP array_map() documentation}
185 * for examples of how the `$callback` parameter works.
186 *
187 * @param callable(T): TCallbackReturn $callback A callable to apply to each
188 * item of the collection.
189 *
190 * @return CollectionInterface<TCallbackReturn>
191 *
192 * @template TCallbackReturn
193 */
194 public function map(callable $callback): self;
195
196 /**
197 * Apply a given callback method on each item of the collection
198 * to reduce it to a single value.
199 *
200 * See the {@link http://php.net/manual/en/function.array-reduce.php PHP array_reduce() documentation}
201 * for examples of how the `$callback` and `$initial` parameters work.
202 *
203 * @param callable(TCarry, T): TCarry $callback A callable to apply to each
204 * item of the collection to reduce it to a single value.
205 * @param TCarry $initial This is the initial value provided to the callback.
206 *
207 * @return TCarry
208 *
209 * @template TCarry
210 */
211 public function reduce(callable $callback, mixed $initial): mixed;
212
213 /**
214 * Create a new collection with divergent items between current and given
215 * collection.
216 *
217 * @param CollectionInterface<T> $other The collection to check for divergent
218 * items.
219 *
220 * @return CollectionInterface<T>
221 *
222 * @throws CollectionMismatchException if the compared collections are of
223 * differing types.
224 */
225 public function diff(CollectionInterface $other): self;
226
227 /**
228 * Create a new collection with intersecting item between current and given
229 * collection.
230 *
231 * @param CollectionInterface<T> $other The collection to check for
232 * intersecting items.
233 *
234 * @return CollectionInterface<T>
235 *
236 * @throws CollectionMismatchException if the compared collections are of
237 * differing types.
238 */
239 public function intersect(CollectionInterface $other): self;
240
241 /**
242 * Merge current items and items of given collections into a new one.
243 *
244 * @param CollectionInterface<T> ...$collections The collections to merge.
245 *
246 * @return CollectionInterface<T>
247 *
248 * @throws CollectionMismatchException if unable to merge any of the given
249 * collections or items within the given collections due to type
250 * mismatch errors.
251 */
252 public function merge(CollectionInterface ...$collections): self;
253 }