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