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 LGPL. 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     public function slice($offset, $length = null);

   243 }