vendor/doctrine/common/lib/Doctrine/Common/Collections/Collection.php

   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
  20 namespace Doctrine\Common\Collections;
  21
  22 use Closure, Countable, IteratorAggregate, ArrayAccess;
  23
  24 /**
  25  * The missing (SPL) Collection/Array/OrderedMap interface.
  26  *
  27  * A Collection resembles the nature of a regular PHP array. That is,
  28  * it is essentially an <b>ordered map</b> that can also be used
  29  * like a list.
  30  *
  31  * A Collection has an internal iterator just like a PHP array. In addition,
  32  * a Collection can be iterated with external iterators, which is preferrable.
  33  * To use an external iterator simply use the foreach language construct to
  34  * iterate over the collection (which calls {@link getIterator()} internally) or
  35  * explicitly retrieve an iterator though {@link getIterator()} which can then be
  36  * used to iterate over the collection.
  37  * You can not rely on the internal iterator of the collection being at a certain
  38  * position unless you explicitly positioned it before. Prefer iteration with
  39  * external iterators.
  40  *
  41  * @since   2.0
  42  * @author  Guilherme Blanco <guilhermeblanco@hotmail.com>
  43  * @author  Jonathan Wage <jonwage@gmail.com>
  44  * @author  Roman Borschel <roman@code-factory.org>
  45  */
  46 interface Collection extends Countable, IteratorAggregate, ArrayAccess
  47 {
  48     /**
  49      * Adds an element at the end of the collection.
  50      *
  51      * @param mixed $element The element to add.
  52      * @return boolean Always TRUE.
  53      */
  54     function add($element);
  55
  56     /**
  57      * Clears the collection, removing all elements.
  58      */
  59     function clear();
  60
  61     /**
  62      * Checks whether an element is contained in the collection.
  63      * This is an O(n) operation, where n is the size of the collection.
  64      *
  65      * @param mixed $element The element to search for.
  66      * @return boolean TRUE if the collection contains the element, FALSE otherwise.
  67      */
  68     function contains($element);
  69
  70     /**
  71      * Checks whether the collection is empty (contains no elements).
  72      *
  73      * @return boolean TRUE if the collection is empty, FALSE otherwise.
  74      */
  75     function isEmpty();
  76
  77     /**
  78      * Removes the element at the specified index from the collection.
  79      *
  80      * @param string|integer $key The kex/index of the element to remove.
  81      * @return mixed The removed element or NULL, if the collection did not contain the element.
  82      */
  83     function remove($key);
  84
  85     /**
  86      * Removes the specified element from the collection, if it is found.
  87      *
  88      * @param mixed $element The element to remove.
  89      * @return boolean TRUE if this collection contained the specified element, FALSE otherwise.
  90      */
  91     function removeElement($element);
  92
  93     /**
  94      * Checks whether the collection contains an element with the specified key/index.
  95      *
  96      * @param string|integer $key The key/index to check for.
  97      * @return boolean TRUE if the collection contains an element with the specified key/index,
  98      *          FALSE otherwise.
  99      */
 100     function containsKey($key);
 101
 102     /**
 103      * Gets the element at the specified key/index.
 104      *
 105      * @param string|integer $key The key/index of the element to retrieve.
 106      * @return mixed
 107      */
 108     function get($key);
 109
 110     /**
 111      * Gets all keys/indices of the collection.
 112      *
 113      * @return array The keys/indices of the collection, in the order of the corresponding
 114      *          elements in the collection.
 115      */
 116     function getKeys();
 117
 118     /**
 119      * Gets all values of the collection.
 120      *
 121      * @return array The values of all elements in the collection, in the order they
 122      *          appear in the collection.
 123      */
 124     function getValues();
 125
 126     /**
 127      * Sets an element in the collection at the specified key/index.
 128      *
 129      * @param string|integer $key The key/index of the element to set.
 130      * @param mixed $value The element to set.
 131      */
 132     function set($key, $value);
 133
 134     /**
 135      * Gets a native PHP array representation of the collection.
 136      *
 137      * @return array
 138      */
 139     function toArray();
 140
 141     /**
 142      * Sets the internal iterator to the first element in the collection and
 143      * returns this element.
 144      *
 145      * @return mixed
 146      */
 147     function first();
 148
 149     /**
 150      * Sets the internal iterator to the last element in the collection and
 151      * returns this element.
 152      *
 153      * @return mixed
 154      */
 155     function last();
 156
 157     /**
 158      * Gets the key/index of the element at the current iterator position.
 159      *
 160      */
 161     function key();
 162
 163     /**
 164      * Gets the element of the collection at the current iterator position.
 165      *
 166      */
 167     function current();
 168
 169     /**
 170      * Moves the internal iterator position to the next element.
 171      *
 172      */
 173     function next();
 174
 175     /**
 176      * Tests for the existence of an element that satisfies the given predicate.
 177      *
 178      * @param Closure $p The predicate.
 179      * @return boolean TRUE if the predicate is TRUE for at least one element, FALSE otherwise.
 180      */
 181     function exists(Closure $p);
 182
 183     /**
 184      * Returns all the elements of this collection that satisfy the predicate p.
 185      * The order of the elements is preserved.
 186      *
 187      * @param Closure $p The predicate used for filtering.
 188      * @return Collection A collection with the results of the filter operation.
 189      */
 190     function filter(Closure $p);
 191
 192     /**
 193      * Applies the given predicate p to all elements of this collection,
 194      * returning true, if the predicate yields true for all elements.
 195      *
 196      * @param Closure $p The predicate.
 197      * @return boolean TRUE, if the predicate yields TRUE for all elements, FALSE otherwise.
 198      */
 199     function forAll(Closure $p);
 200
 201     /**
 202      * Applies the given function to each element in the collection and returns
 203      * a new collection with the elements returned by the function.
 204      *
 205      * @param Closure $func
 206      * @return Collection
 207      */
 208     function map(Closure $func);
 209
 210     /**
 211      * Partitions this collection in two collections according to a predicate.
 212      * Keys are preserved in the resulting collections.
 213      *
 214      * @param Closure $p The predicate on which to partition.
 215      * @return array An array with two elements. The first element contains the collection
 216      *               of elements where the predicate returned TRUE, the second element
 217      *               contains the collection of elements where the predicate returned FALSE.
 218      */
 219     function partition(Closure $p);
 220
 221     /**
 222      * Gets the index/key of a given element. The comparison of two elements is strict,
 223      * that means not only the value but also the type must match.
 224      * For objects this means reference equality.
 225      *
 226      * @param mixed $element The element to search for.
 227      * @return mixed The key/index of the element or FALSE if the element was not found.
 228      */
 229     function indexOf($element);
 230
 231     /**
 232      * Extract a slice of $length elements starting at position $offset from the Collection.
 233      *
 234      * If $length is null it returns all elements from $offset to the end of the Collection.
 235      * Keys have to be preserved by this method. Calling this method will only return the
 236      * selected slice and NOT change the elements contained in the collection slice is called on.
 237      *
 238      * @param int $offset
 239      * @param int $length
 240      * @return array
 241      */
 242     function slice($offset, $length = null);
 243 }