interface Collection in Plug 7

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 <[e-mail]> @author Jonathan Wage <[e-mail]> @author Roman Borschel <[e-mail]>

Hierarchy

• interface \Doctrine\Common\Collections\Collection extends \Countable \IteratorAggregate \ArrayAccess

2 files declare their use of Collection

CollectionTest.php in lib/doctrine/collections/tests/Doctrine/Tests/Common/Collections/CollectionTest.php

PersistentObject.php in lib/doctrine/common/lib/Doctrine/Common/Persistence/PersistentObject.php

File

lib/doctrine/collections/lib/Doctrine/Common/Collections/Collection.php, line 49

Namespace

Doctrine\Common\Collections

interface Collection extends Countable, IteratorAggregate, ArrayAccess {

  /**
   * Adds an element at the end of the collection.
   *
   * @param mixed $element The element to add.
   *
   * @return boolean 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 boolean TRUE if the collection contains the element, FALSE otherwise.
   */
  public function contains($element);

  /**
   * Checks whether the collection is empty (contains no elements).
   *
   * @return boolean TRUE if the collection is empty, FALSE otherwise.
   */
  public function isEmpty();

  /**
   * Removes the element at the specified index from the collection.
   *
   * @param string|integer $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 boolean 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|integer $key The key/index to check for.
   *
   * @return boolean 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|integer $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|integer $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 boolean 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 boolean 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 array 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);

}

Members

Name	Modifiers	Type	Description	Overrides
Collection::add	public	function	Adds an element at the end of the collection.	2
Collection::clear	public	function	Clears the collection, removing all elements.	2
Collection::contains	public	function	Checks whether an element is contained in the collection. This is an O(n) operation, where n is the size of the collection.	2
Collection::containsKey	public	function	Checks whether the collection contains an element with the specified key/index.	2
Collection::current	public	function	Gets the element of the collection at the current iterator position.	2
Collection::exists	public	function	Tests for the existence of an element that satisfies the given predicate.	2
Collection::filter	public	function	Returns all the elements of this collection that satisfy the predicate p. The order of the elements is preserved.	2
Collection::first	public	function	Sets the internal iterator to the first element in the collection and returns this element.	2
Collection::forAll	public	function	Tests whether the given predicate p holds for all elements of this collection.	2
Collection::get	public	function	Gets the element at the specified key/index.	2
Collection::getKeys	public	function	Gets all keys/indices of the collection.	2
Collection::getValues	public	function	Gets all values of the collection.	2
Collection::indexOf	public	function	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.	2
Collection::isEmpty	public	function	Checks whether the collection is empty (contains no elements).	2
Collection::key	public	function	Gets the key/index of the element at the current iterator position.	2
Collection::last	public	function	Sets the internal iterator to the last element in the collection and returns this element.	2
Collection::map	public	function	Applies the given function to each element in the collection and returns a new collection with the elements returned by the function.	2
Collection::next	public	function	Moves the internal iterator position to the next element and returns this element.	2
Collection::partition	public	function	Partitions this collection in two collections according to a predicate. Keys are preserved in the resulting collections.	2
Collection::remove	public	function	Removes the element at the specified index from the collection.	2
Collection::removeElement	public	function	Removes the specified element from the collection, if it is found.	2
Collection::set	public	function	Sets an element in the collection at the specified key/index.	2
Collection::slice	public	function	Extracts a slice of $length elements starting at position $offset from the Collection.	2
Collection::toArray	public	function	Gets a native PHP array representation of the collection.	2