You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
263 lines
8.5 KiB
263 lines
8.5 KiB
<?php |
|
/* |
|
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
|
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
|
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
|
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |
|
* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
|
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
|
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
|
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
|
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
|
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
|
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
|
* |
|
* This software consists of voluntary contributions made by many individuals |
|
* and is licensed under the MIT license. For more information, see |
|
* <http://www.doctrine-project.org>. |
|
*/ |
|
|
|
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 <b>ordered map</b> 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 <guilhermeblanco@hotmail.com> |
|
* @author Jonathan Wage <jonwage@gmail.com> |
|
* @author Roman Borschel <roman@code-factory.org> |
|
*/ |
|
interface Collection extends Countable, IteratorAggregate, ArrayAccess |
|
{ |
|
/** |
|
* Adds an element at the end of the collection. |
|
* |
|
* @param mixed $element The element to add. |
|
* |
|
* @return bool 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 bool TRUE if the collection contains the element, FALSE otherwise. |
|
*/ |
|
public function contains($element); |
|
|
|
/** |
|
* Checks whether the collection is empty (contains no elements). |
|
* |
|
* @return bool TRUE if the collection is empty, FALSE otherwise. |
|
*/ |
|
public function isEmpty(); |
|
|
|
/** |
|
* Removes the element at the specified index from the collection. |
|
* |
|
* @param string|int $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 bool 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|int $key The key/index to check for. |
|
* |
|
* @return bool 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|int $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|int $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 bool 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 bool 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 Collection[] 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); |
|
}
|
|
|