. */ namespace Doctrine\Common\Collections; use ArrayAccess; use Closure; use Countable; use IteratorAggregate; /** * The missing (SPL) Collection/Array/OrderedMap interface. * * A Collection resembles the nature of a regular PHP array. That is, * it is essentially an ordered map that can also be used * like a list. * * A Collection has an internal iterator just like a PHP array. In addition, * a Collection can be iterated with external iterators, which is preferable. * To use an external iterator simply use the foreach language construct to * iterate over the collection (which calls {@link getIterator()} internally) or * explicitly retrieve an iterator though {@link getIterator()} which can then be * used to iterate over the collection. * You can not rely on the internal iterator of the collection being at a certain * position unless you explicitly positioned it before. Prefer iteration with * external iterators. * * @since 2.0 * @author Guilherme Blanco * @author Jonathan Wage * @author Roman Borschel */ interface Collection extends Countable, IteratorAggregate, ArrayAccess { /** * Adds an element at the end of the collection. * * @param mixed $element The element to add. * * @return boolean Always TRUE. */ public function add($element); /** * Clears the collection, removing all elements. * * @return void */ public function clear(); /** * Checks whether an element is contained in the collection. * This is an O(n) operation, where n is the size of the collection. * * @param mixed $element The element to search for. * * @return boolean TRUE if the collection contains the element, FALSE otherwise. */ public function contains($element); /** * Checks whether the collection is empty (contains no elements). * * @return boolean TRUE if the collection is empty, FALSE otherwise. */ public function isEmpty(); /** * Removes the element at the specified index from the collection. * * @param string|integer $key The kex/index of the element to remove. * * @return mixed The removed element or NULL, if the collection did not contain the element. */ public function remove($key); /** * Removes the specified element from the collection, if it is found. * * @param mixed $element The element to remove. * * @return boolean TRUE if this collection contained the specified element, FALSE otherwise. */ public function removeElement($element); /** * Checks whether the collection contains an element with the specified key/index. * * @param string|integer $key The key/index to check for. * * @return boolean TRUE if the collection contains an element with the specified key/index, * FALSE otherwise. */ public function containsKey($key); /** * Gets the element at the specified key/index. * * @param string|integer $key The key/index of the element to retrieve. * * @return mixed */ public function get($key); /** * Gets all keys/indices of the collection. * * @return array The keys/indices of the collection, in the order of the corresponding * elements in the collection. */ public function getKeys(); /** * Gets all values of the collection. * * @return array The values of all elements in the collection, in the order they * appear in the collection. */ public function getValues(); /** * Sets an element in the collection at the specified key/index. * * @param string|integer $key The key/index of the element to set. * @param mixed $value The element to set. * * @return void */ public function set($key, $value); /** * Gets a native PHP array representation of the collection. * * @return array */ public function toArray(); /** * Sets the internal iterator to the first element in the collection and returns this element. * * @return mixed */ public function first(); /** * Sets the internal iterator to the last element in the collection and returns this element. * * @return mixed */ public function last(); /** * Gets the key/index of the element at the current iterator position. * * @return int|string */ public function key(); /** * Gets the element of the collection at the current iterator position. * * @return mixed */ public function current(); /** * Moves the internal iterator position to the next element and returns this element. * * @return mixed */ public function next(); /** * Tests for the existence of an element that satisfies the given predicate. * * @param Closure $p The predicate. * * @return boolean TRUE if the predicate is TRUE for at least one element, FALSE otherwise. */ public function exists(Closure $p); /** * Returns all the elements of this collection that satisfy the predicate p. * The order of the elements is preserved. * * @param Closure $p The predicate used for filtering. * * @return Collection A collection with the results of the filter operation. */ public function filter(Closure $p); /** * Tests whether the given predicate p holds for all elements of this collection. * * @param Closure $p The predicate. * * @return boolean TRUE, if the predicate yields TRUE for all elements, FALSE otherwise. */ public function forAll(Closure $p); /** * Applies the given function to each element in the collection and returns * a new collection with the elements returned by the function. * * @param Closure $func * * @return Collection */ public function map(Closure $func); /** * Partitions this collection in two collections according to a predicate. * Keys are preserved in the resulting collections. * * @param Closure $p The predicate on which to partition. * * @return array An array with two elements. The first element contains the collection * of elements where the predicate returned TRUE, the second element * contains the collection of elements where the predicate returned FALSE. */ public function partition(Closure $p); /** * Gets the index/key of a given element. The comparison of two elements is strict, * that means not only the value but also the type must match. * For objects this means reference equality. * * @param mixed $element The element to search for. * * @return int|string|bool The key/index of the element or FALSE if the element was not found. */ public function indexOf($element); /** * Extracts a slice of $length elements starting at position $offset from the Collection. * * If $length is null it returns all elements from $offset to the end of the Collection. * Keys have to be preserved by this method. Calling this method will only return the * selected slice and NOT change the elements contained in the collection slice is called on. * * @param int $offset The offset to start from. * @param int|null $length The maximum number of elements to return, or null for no limit. * * @return array */ public function slice($offset, $length = null); }