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

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

190 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 <ben@benramsey.com>
10	* @license http://opensource.org/licenses/MIT MIT
11	*/
12	declare (strict_types=1);
13	namespace Dudlewebs\WPMCS\Ramsey\Collection;
14
15	/**
16	* A collection represents a group of objects, known as its elements.
17	*
18	* Some collections allow duplicate elements and others do not. Some are ordered
19	* and others unordered.
20	*
21	* @template T
22	* @extends ArrayInterface<T>
23	*/
24	interface CollectionInterface extends ArrayInterface
25	{
26	/**
27	* Ascending sort type.
28	*/
29	public const SORT_ASC = 'asc';
30	/**
31	* Descending sort type.
32	*/
33	public const SORT_DESC = 'desc';
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	// phpcs:ignore SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint
59	public function add($element): bool;
60	/**
61	* Returns `true` if this collection contains the specified element.
62	*
63	* @param T $element The element to check whether the collection contains.
64	* @param bool $strict Whether to perform a strict type check on the value.
65	*/
66	// phpcs:ignore SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint
67	public function contains($element, bool $strict = \true): bool;
68	/**
69	* Returns the type associated with this collection.
70	*/
71	public function getType(): string;
72	/**
73	* Removes a single instance of the specified element from this collection,
74	* if it is present.
75	*
76	* @param T $element The element to remove from the collection.
77	*
78	* @return bool `true` if an element was removed as a result of this call.
79	*/
80	// phpcs:ignore SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint
81	public function remove($element): bool;
82	/**
83	* Returns the values from the given property or method.
84	*
85	* @param string $propertyOrMethod The property or method name to filter by.
86	*
87	* @return list<mixed>
88	*/
89	public function column(string $propertyOrMethod): array;
90	/**
91	* Returns the first item of the collection.
92	*
93	* @return T
94	*/
95	public function first();
96	/**
97	* Returns the last item of the collection.
98	*
99	* @return T
100	*/
101	public function last();
102	/**
103	* Sort the collection by a property or method with the given sort order.
104	*
105	* This will always leave the original collection untouched and will return
106	* a new one.
107	*
108	* @param string $propertyOrMethod The property or method to sort by.
109	* @param string $order The sort order for the resulting collection (one of
110	* this interface's `SORT_*` constants).
111	*
112	* @return CollectionInterface<T>
113	*/
114	public function sort(string $propertyOrMethod, string $order = self::SORT_ASC): self;
115	/**
116	* Filter out items of the collection which don't match the criteria of
117	* given callback.
118	*
119	* This will always leave the original collection untouched and will return
120	* a new one.
121	*
122	* See the {@link http://php.net/manual/en/function.array-filter.php PHP array_filter() documentation}
123	* for examples of how the `$callback` parameter works.
124	*
125	* @param callable(T):bool $callback A callable to use for filtering elements.
126	*
127	* @return CollectionInterface<T>
128	*/
129	public function filter(callable $callback): self;
130	/**
131	* Create a new collection where items match the criteria of given callback.
132	*
133	* This will always leave the original collection untouched and will return
134	* a new one.
135	*
136	* @param string $propertyOrMethod The property or method to evaluate.
137	* @param mixed $value The value to match.
138	*
139	* @return CollectionInterface<T>
140	*/
141	// phpcs:ignore SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint
142	public function where(string $propertyOrMethod, $value): self;
143	/**
144	* Apply a given callback method on each item of the collection.
145	*
146	* This will always leave the original collection untouched. The new
147	* collection is created by mapping the callback to each item of the
148	* original collection.
149	*
150	* See the {@link http://php.net/manual/en/function.array-map.php PHP array_map() documentation}
151	* for examples of how the `$callback` parameter works.
152	*
153	* @param callable(T):TCallbackReturn $callback A callable to apply to each
154	* item of the collection.
155	*
156	* @return CollectionInterface<TCallbackReturn>
157	*
158	* @template TCallbackReturn
159	*/
160	public function map(callable $callback): self;
161	/**
162	* Create a new collection with divergent items between current and given
163	* collection.
164	*
165	* @param CollectionInterface<T> $other The collection to check for divergent
166	* items.
167	*
168	* @return CollectionInterface<T>
169	*/
170	public function diff(CollectionInterface $other): self;
171	/**
172	* Create a new collection with intersecting item between current and given
173	* collection.
174	*
175	* @param CollectionInterface<T> $other The collection to check for
176	* intersecting items.
177	*
178	* @return CollectionInterface<T>
179	*/
180	public function intersect(CollectionInterface $other): self;
181	/**
182	* Merge current items and items of given collections into a new one.
183	*
184	* @param CollectionInterface<T> ...$collections The collections to merge.
185	*
186	* @return CollectionInterface<T>
187	*/
188	public function merge(CollectionInterface ...$collections): self;
189	}
190