Chris@0: <?php
Chris@0: /*
Chris@0:  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
Chris@0:  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
Chris@0:  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
Chris@0:  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
Chris@0:  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
Chris@0:  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
Chris@0:  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
Chris@0:  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
Chris@0:  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
Chris@0:  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
Chris@0:  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Chris@0:  *
Chris@0:  * This software consists of voluntary contributions made by many individuals
Chris@0:  * and is licensed under the MIT license. For more information, see
Chris@0:  * <http://www.doctrine-project.org>.
Chris@0:  */
Chris@0: 
Chris@0: namespace Doctrine\Common\Collections;
Chris@0: 
Chris@0: use ArrayAccess;
Chris@0: use Closure;
Chris@0: use Countable;
Chris@0: use IteratorAggregate;
Chris@0: 
Chris@0: /**
Chris@0:  * The missing (SPL) Collection/Array/OrderedMap interface.
Chris@0:  *
Chris@0:  * A Collection resembles the nature of a regular PHP array. That is,
Chris@0:  * it is essentially an <b>ordered map</b> that can also be used
Chris@0:  * like a list.
Chris@0:  *
Chris@0:  * A Collection has an internal iterator just like a PHP array. In addition,
Chris@0:  * a Collection can be iterated with external iterators, which is preferable.
Chris@0:  * To use an external iterator simply use the foreach language construct to
Chris@0:  * iterate over the collection (which calls {@link getIterator()} internally) or
Chris@0:  * explicitly retrieve an iterator though {@link getIterator()} which can then be
Chris@0:  * used to iterate over the collection.
Chris@0:  * You can not rely on the internal iterator of the collection being at a certain
Chris@0:  * position unless you explicitly positioned it before. Prefer iteration with
Chris@0:  * external iterators.
Chris@0:  *
Chris@0:  * @since  2.0
Chris@0:  * @author Guilherme Blanco <guilhermeblanco@hotmail.com>
Chris@0:  * @author Jonathan Wage <jonwage@gmail.com>
Chris@0:  * @author Roman Borschel <roman@code-factory.org>
Chris@0:  */
Chris@0: interface Collection extends Countable, IteratorAggregate, ArrayAccess
Chris@0: {
Chris@0:     /**
Chris@0:      * Adds an element at the end of the collection.
Chris@0:      *
Chris@0:      * @param mixed $element The element to add.
Chris@0:      *
Chris@0:      * @return boolean Always TRUE.
Chris@0:      */
Chris@0:     public function add($element);
Chris@0: 
Chris@0:     /**
Chris@0:      * Clears the collection, removing all elements.
Chris@0:      *
Chris@0:      * @return void
Chris@0:      */
Chris@0:     public function clear();
Chris@0: 
Chris@0:     /**
Chris@0:      * Checks whether an element is contained in the collection.
Chris@0:      * This is an O(n) operation, where n is the size of the collection.
Chris@0:      *
Chris@0:      * @param mixed $element The element to search for.
Chris@0:      *
Chris@0:      * @return boolean TRUE if the collection contains the element, FALSE otherwise.
Chris@0:      */
Chris@0:     public function contains($element);
Chris@0: 
Chris@0:     /**
Chris@0:      * Checks whether the collection is empty (contains no elements).
Chris@0:      *
Chris@0:      * @return boolean TRUE if the collection is empty, FALSE otherwise.
Chris@0:      */
Chris@0:     public function isEmpty();
Chris@0: 
Chris@0:     /**
Chris@0:      * Removes the element at the specified index from the collection.
Chris@0:      *
Chris@0:      * @param string|integer $key The kex/index of the element to remove.
Chris@0:      *
Chris@0:      * @return mixed The removed element or NULL, if the collection did not contain the element.
Chris@0:      */
Chris@0:     public function remove($key);
Chris@0: 
Chris@0:     /**
Chris@0:      * Removes the specified element from the collection, if it is found.
Chris@0:      *
Chris@0:      * @param mixed $element The element to remove.
Chris@0:      *
Chris@0:      * @return boolean TRUE if this collection contained the specified element, FALSE otherwise.
Chris@0:      */
Chris@0:     public function removeElement($element);
Chris@0: 
Chris@0:     /**
Chris@0:      * Checks whether the collection contains an element with the specified key/index.
Chris@0:      *
Chris@0:      * @param string|integer $key The key/index to check for.
Chris@0:      *
Chris@0:      * @return boolean TRUE if the collection contains an element with the specified key/index,
Chris@0:      *                 FALSE otherwise.
Chris@0:      */
Chris@0:     public function containsKey($key);
Chris@0: 
Chris@0:     /**
Chris@0:      * Gets the element at the specified key/index.
Chris@0:      *
Chris@0:      * @param string|integer $key The key/index of the element to retrieve.
Chris@0:      *
Chris@0:      * @return mixed
Chris@0:      */
Chris@0:     public function get($key);
Chris@0: 
Chris@0:     /**
Chris@0:      * Gets all keys/indices of the collection.
Chris@0:      *
Chris@0:      * @return array The keys/indices of the collection, in the order of the corresponding
Chris@0:      *               elements in the collection.
Chris@0:      */
Chris@0:     public function getKeys();
Chris@0: 
Chris@0:     /**
Chris@0:      * Gets all values of the collection.
Chris@0:      *
Chris@0:      * @return array The values of all elements in the collection, in the order they
Chris@0:      *               appear in the collection.
Chris@0:      */
Chris@0:     public function getValues();
Chris@0: 
Chris@0:     /**
Chris@0:      * Sets an element in the collection at the specified key/index.
Chris@0:      *
Chris@0:      * @param string|integer $key   The key/index of the element to set.
Chris@0:      * @param mixed          $value The element to set.
Chris@0:      *
Chris@0:      * @return void
Chris@0:      */
Chris@0:     public function set($key, $value);
Chris@0: 
Chris@0:     /**
Chris@0:      * Gets a native PHP array representation of the collection.
Chris@0:      *
Chris@0:      * @return array
Chris@0:      */
Chris@0:     public function toArray();
Chris@0: 
Chris@0:     /**
Chris@0:      * Sets the internal iterator to the first element in the collection and returns this element.
Chris@0:      *
Chris@0:      * @return mixed
Chris@0:      */
Chris@0:     public function first();
Chris@0: 
Chris@0:     /**
Chris@0:      * Sets the internal iterator to the last element in the collection and returns this element.
Chris@0:      *
Chris@0:      * @return mixed
Chris@0:      */
Chris@0:     public function last();
Chris@0: 
Chris@0:     /**
Chris@0:      * Gets the key/index of the element at the current iterator position.
Chris@0:      *
Chris@0:      * @return int|string
Chris@0:      */
Chris@0:     public function key();
Chris@0: 
Chris@0:     /**
Chris@0:      * Gets the element of the collection at the current iterator position.
Chris@0:      *
Chris@0:      * @return mixed
Chris@0:      */
Chris@0:     public function current();
Chris@0: 
Chris@0:     /**
Chris@0:      * Moves the internal iterator position to the next element and returns this element.
Chris@0:      *
Chris@0:      * @return mixed
Chris@0:      */
Chris@0:     public function next();
Chris@0: 
Chris@0:     /**
Chris@0:      * Tests for the existence of an element that satisfies the given predicate.
Chris@0:      *
Chris@0:      * @param Closure $p The predicate.
Chris@0:      *
Chris@0:      * @return boolean TRUE if the predicate is TRUE for at least one element, FALSE otherwise.
Chris@0:      */
Chris@0:     public function exists(Closure $p);
Chris@0: 
Chris@0:     /**
Chris@0:      * Returns all the elements of this collection that satisfy the predicate p.
Chris@0:      * The order of the elements is preserved.
Chris@0:      *
Chris@0:      * @param Closure $p The predicate used for filtering.
Chris@0:      *
Chris@0:      * @return Collection A collection with the results of the filter operation.
Chris@0:      */
Chris@0:     public function filter(Closure $p);
Chris@0: 
Chris@0:     /**
Chris@0:      * Tests whether the given predicate p holds for all elements of this collection.
Chris@0:      *
Chris@0:      * @param Closure $p The predicate.
Chris@0:      *
Chris@0:      * @return boolean TRUE, if the predicate yields TRUE for all elements, FALSE otherwise.
Chris@0:      */
Chris@0:     public function forAll(Closure $p);
Chris@0: 
Chris@0:     /**
Chris@0:      * Applies the given function to each element in the collection and returns
Chris@0:      * a new collection with the elements returned by the function.
Chris@0:      *
Chris@0:      * @param Closure $func
Chris@0:      *
Chris@0:      * @return Collection
Chris@0:      */
Chris@0:     public function map(Closure $func);
Chris@0: 
Chris@0:     /**
Chris@0:      * Partitions this collection in two collections according to a predicate.
Chris@0:      * Keys are preserved in the resulting collections.
Chris@0:      *
Chris@0:      * @param Closure $p The predicate on which to partition.
Chris@0:      *
Chris@0:      * @return array An array with two elements. The first element contains the collection
Chris@0:      *               of elements where the predicate returned TRUE, the second element
Chris@0:      *               contains the collection of elements where the predicate returned FALSE.
Chris@0:      */
Chris@0:     public function partition(Closure $p);
Chris@0: 
Chris@0:     /**
Chris@0:      * Gets the index/key of a given element. The comparison of two elements is strict,
Chris@0:      * that means not only the value but also the type must match.
Chris@0:      * For objects this means reference equality.
Chris@0:      *
Chris@0:      * @param mixed $element The element to search for.
Chris@0:      *
Chris@0:      * @return int|string|bool The key/index of the element or FALSE if the element was not found.
Chris@0:      */
Chris@0:     public function indexOf($element);
Chris@0: 
Chris@0:     /**
Chris@0:      * Extracts a slice of $length elements starting at position $offset from the Collection.
Chris@0:      *
Chris@0:      * If $length is null it returns all elements from $offset to the end of the Collection.
Chris@0:      * Keys have to be preserved by this method. Calling this method will only return the
Chris@0:      * selected slice and NOT change the elements contained in the collection slice is called on.
Chris@0:      *
Chris@0:      * @param int      $offset The offset to start from.
Chris@0:      * @param int|null $length The maximum number of elements to return, or null for no limit.
Chris@0:      *
Chris@0:      * @return array
Chris@0:      */
Chris@0:     public function slice($offset, $length = null);
Chris@0: }