www.aleph1.co.uk Git - yaffs-website/blob - vendor/doctrine/collections/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 ArrayAccess;
  23 use Closure;
  24 use Countable;
  25 use 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  */
  49 interface 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 bool 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 bool 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 bool 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|int $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 bool 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|int $key The key/index to check for.
 106      *
 107      * @return bool 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|int $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|int $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 bool 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 bool 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 Collection[] 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 }