media-cloud-sync / includes / sdk / google / ramsey / collection / src / CollectionInterface.php

CollectionInterface.php in Media Cloud Sync 1.4.1, at includes/sdk/google/ramsey/collection/src/CollectionInterface.php

237 lines 9.1 KB

Raw Download Zip

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