defender-security / vendor / ramsey / collection / src / CollectionInterface.php

CollectionInterface.php in Defender Security – Malware Scanner, Login Security & Firewall 5.4.0, at vendor/ramsey/collection/src/CollectionInterface.php

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