1<?php
2/*
3 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
4 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
5 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
6 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
7 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
8 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
9 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
10 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
11 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
12 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
13 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
14 *
15 * This software consists of voluntary contributions made by many individuals
16 * and is licensed under the MIT license. For more information, see
17 * <http://www.doctrine-project.org>.
18 */
19
20namespace Doctrine\Common\Collections;
21
22use ArrayAccess;
23use Closure;
24use Countable;
25use IteratorAggregate;
26
27/**
28 * The missing (SPL) Collection/Array/OrderedMap interface.
29 *
30 * A Collection resembles the nature of a regular PHP array. That is,
31 * it is essentially an <b>ordered map</b> that can also be used
32 * like a list.
33 *
34 * A Collection has an internal iterator just like a PHP array. In addition,
35 * a Collection can be iterated with external iterators, which is preferable.
36 * To use an external iterator simply use the foreach language construct to
37 * iterate over the collection (which calls {@link getIterator()} internally) or
38 * explicitly retrieve an iterator though {@link getIterator()} which can then be
39 * used to iterate over the collection.
40 * You can not rely on the internal iterator of the collection being at a certain
41 * position unless you explicitly positioned it before. Prefer iteration with
42 * external iterators.
43 *
44 * @since  2.0
45 * @author Guilherme Blanco <guilhermeblanco@hotmail.com>
46 * @author Jonathan Wage <jonwage@gmail.com>
47 * @author Roman Borschel <roman@code-factory.org>
48 */
49interface Collection extends Countable, IteratorAggregate, ArrayAccess
50{
51    /**
52     * Adds an element at the end of the collection.
53     *
54     * @param mixed $element The element to add.
55     *
56     * @return boolean Always TRUE.
57     */
58    public function add($element);
59
60    /**
61     * Clears the collection, removing all elements.
62     *
63     * @return void
64     */
65    public function clear();
66
67    /**
68     * Checks whether an element is contained in the collection.
69     * This is an O(n) operation, where n is the size of the collection.
70     *
71     * @param mixed $element The element to search for.
72     *
73     * @return boolean TRUE if the collection contains the element, FALSE otherwise.
74     */
75    public function contains($element);
76
77    /**
78     * Checks whether the collection is empty (contains no elements).
79     *
80     * @return boolean TRUE if the collection is empty, FALSE otherwise.
81     */
82    public function isEmpty();
83
84    /**
85     * Removes the element at the specified index from the collection.
86     *
87     * @param string|integer $key The kex/index of the element to remove.
88     *
89     * @return mixed The removed element or NULL, if the collection did not contain the element.
90     */
91    public function remove($key);
92
93    /**
94     * Removes the specified element from the collection, if it is found.
95     *
96     * @param mixed $element The element to remove.
97     *
98     * @return boolean TRUE if this collection contained the specified element, FALSE otherwise.
99     */
100    public function removeElement($element);
101
102    /**
103     * Checks whether the collection contains an element with the specified key/index.
104     *
105     * @param string|integer $key The key/index to check for.
106     *
107     * @return boolean TRUE if the collection contains an element with the specified key/index,
108     *                 FALSE otherwise.
109     */
110    public function containsKey($key);
111
112    /**
113     * Gets the element at the specified key/index.
114     *
115     * @param string|integer $key The key/index of the element to retrieve.
116     *
117     * @return mixed
118     */
119    public function get($key);
120
121    /**
122     * Gets all keys/indices of the collection.
123     *
124     * @return array The keys/indices of the collection, in the order of the corresponding
125     *               elements in the collection.
126     */
127    public function getKeys();
128
129    /**
130     * Gets all values of the collection.
131     *
132     * @return array The values of all elements in the collection, in the order they
133     *               appear in the collection.
134     */
135    public function getValues();
136
137    /**
138     * Sets an element in the collection at the specified key/index.
139     *
140     * @param string|integer $key   The key/index of the element to set.
141     * @param mixed          $value The element to set.
142     *
143     * @return void
144     */
145    public function set($key, $value);
146
147    /**
148     * Gets a native PHP array representation of the collection.
149     *
150     * @return array
151     */
152    public function toArray();
153
154    /**
155     * Sets the internal iterator to the first element in the collection and returns this element.
156     *
157     * @return mixed
158     */
159    public function first();
160
161    /**
162     * Sets the internal iterator to the last element in the collection and returns this element.
163     *
164     * @return mixed
165     */
166    public function last();
167
168    /**
169     * Gets the key/index of the element at the current iterator position.
170     *
171     * @return int|string
172     */
173    public function key();
174
175    /**
176     * Gets the element of the collection at the current iterator position.
177     *
178     * @return mixed
179     */
180    public function current();
181
182    /**
183     * Moves the internal iterator position to the next element and returns this element.
184     *
185     * @return mixed
186     */
187    public function next();
188
189    /**
190     * Tests for the existence of an element that satisfies the given predicate.
191     *
192     * @param Closure $p The predicate.
193     *
194     * @return boolean TRUE if the predicate is TRUE for at least one element, FALSE otherwise.
195     */
196    public function exists(Closure $p);
197
198    /**
199     * Returns all the elements of this collection that satisfy the predicate p.
200     * The order of the elements is preserved.
201     *
202     * @param Closure $p The predicate used for filtering.
203     *
204     * @return Collection A collection with the results of the filter operation.
205     */
206    public function filter(Closure $p);
207
208    /**
209     * Tests whether the given predicate p holds for all elements of this collection.
210     *
211     * @param Closure $p The predicate.
212     *
213     * @return boolean TRUE, if the predicate yields TRUE for all elements, FALSE otherwise.
214     */
215    public function forAll(Closure $p);
216
217    /**
218     * Applies the given function to each element in the collection and returns
219     * a new collection with the elements returned by the function.
220     *
221     * @param Closure $func
222     *
223     * @return Collection
224     */
225    public function map(Closure $func);
226
227    /**
228     * Partitions this collection in two collections according to a predicate.
229     * Keys are preserved in the resulting collections.
230     *
231     * @param Closure $p The predicate on which to partition.
232     *
233     * @return array An array with two elements. The first element contains the collection
234     *               of elements where the predicate returned TRUE, the second element
235     *               contains the collection of elements where the predicate returned FALSE.
236     */
237    public function partition(Closure $p);
238
239    /**
240     * Gets the index/key of a given element. The comparison of two elements is strict,
241     * that means not only the value but also the type must match.
242     * For objects this means reference equality.
243     *
244     * @param mixed $element The element to search for.
245     *
246     * @return int|string|bool The key/index of the element or FALSE if the element was not found.
247     */
248    public function indexOf($element);
249
250    /**
251     * Extracts a slice of $length elements starting at position $offset from the Collection.
252     *
253     * If $length is null it returns all elements from $offset to the end of the Collection.
254     * Keys have to be preserved by this method. Calling this method will only return the
255     * selected slice and NOT change the elements contained in the collection slice is called on.
256     *
257     * @param int      $offset The offset to start from.
258     * @param int|null $length The maximum number of elements to return, or null for no limit.
259     *
260     * @return array
261     */
262    public function slice($offset, $length = null);
263}
264