ArrayCollection.php

<?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 Closure, ArrayIterator;
use Doctrine\Common\Collections\Expr\Expression;
use Doctrine\Common\Collections\Expr\ClosureExpressionVisitor;

/**
 * An ArrayCollection is a Collection implementation that wraps a regular PHP array.
 *
 * @since   2.0
 * @author  Guilherme Blanco <guilhermeblanco@hotmail.com>
 * @author  Jonathan Wage <jonwage@gmail.com>
 * @author  Roman Borschel <roman@code-factory.org>
 */
class ArrayCollection implements Collection, Selectable {

  /**
   * An array containing the entries of this collection.
   *
   * @var array
   */
  private $_elements;

  /**
   * Initializes a new ArrayCollection.
   *
   * @param array $elements
   */
  public function __construct(array $elements = array()) {
    $this->_elements = $elements;
  }

  /**
   * Gets the PHP array representation of this collection.
   *
   * @return array The PHP array representation of this collection.
   */
  public function toArray() {
    return $this->_elements;
  }

  /**
   * Sets the internal iterator to the first element in the collection and
   * returns this element.
   *
   * @return mixed
   */
  public function first() {
    return reset($this->_elements);
  }

  /**
   * Sets the internal iterator to the last element in the collection and
   * returns this element.
   *
   * @return mixed
   */
  public function last() {
    return end($this->_elements);
  }

  /**
   * Gets the current key/index at the current internal iterator position.
   *
   * @return mixed
   */
  public function key() {
    return key($this->_elements);
  }

  /**
   * Moves the internal iterator position to the next element.
   *
   * @return mixed
   */
  public function next() {
    return next($this->_elements);
  }

  /**
   * Gets the element of the collection at the current internal iterator position.
   *
   * @return mixed
   */
  public function current() {
    return current($this->_elements);
  }

  /**
   * Removes an element with a specific key/index from the collection.
   *
   * @param mixed $key
   * @return mixed The removed element or NULL, if no element exists for the given key.
   */
  public function remove($key) {
    if (isset($this->_elements[$key])) {
      $removed = $this->_elements[$key];
      unset($this->_elements[$key]);
      return $removed;
    }
    return null;
  }

  /**
   * 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) {
    $key = array_search($element, $this->_elements, true);
    if ($key !== false) {
      unset($this->_elements[$key]);
      return true;
    }
    return false;
  }

  /**
   * ArrayAccess implementation of offsetExists()
   *
   * @see containsKey()
   *
   * @param mixed $offset
   * @return bool
   */
  public function offsetExists($offset) {
    return $this
      ->containsKey($offset);
  }

  /**
   * ArrayAccess implementation of offsetGet()
   *
   * @see get()
   *
   * @param mixed $offset
   * @return mixed
   */
  public function offsetGet($offset) {
    return $this
      ->get($offset);
  }

  /**
   * ArrayAccess implementation of offsetSet()
   *
   * @see add()
   * @see set()
   *
   * @param mixed $offset
   * @param mixed $value
   * @return bool
   */
  public function offsetSet($offset, $value) {
    if (!isset($offset)) {
      return $this
        ->add($value);
    }
    return $this
      ->set($offset, $value);
  }

  /**
   * ArrayAccess implementation of offsetUnset()
   *
   * @see remove()
   *
   * @param mixed $offset
   * @return mixed
   */
  public function offsetUnset($offset) {
    return $this
      ->remove($offset);
  }

  /**
   * Checks whether the collection contains a specific key/index.
   *
   * @param mixed $key The key to check for.
   * @return boolean TRUE if the given key/index exists, FALSE otherwise.
   */
  public function containsKey($key) {
    return isset($this->_elements[$key]);
  }

  /**
   * Checks whether the given element is contained in the collection.
   * Only element values are compared, not keys. 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
   * @return boolean TRUE if the given element is contained in the collection,
   *          FALSE otherwise.
   */
  public function contains($element) {
    foreach ($this->_elements as $collectionElement) {
      if ($element === $collectionElement) {
        return true;
      }
    }
    return false;
  }

  /**
   * 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) {
    foreach ($this->_elements as $key => $element) {
      if ($p($key, $element)) {
        return true;
      }
    }
    return false;
  }

  /**
   * Searches for a given element and, if found, returns the corresponding key/index
   * of that 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 mixed The key/index of the element or FALSE if the element was not found.
   */
  public function indexOf($element) {
    return array_search($element, $this->_elements, true);
  }

  /**
   * Gets the element with the given key/index.
   *
   * @param mixed $key The key.
   * @return mixed The element or NULL, if no element exists for the given key.
   */
  public function get($key) {
    if (isset($this->_elements[$key])) {
      return $this->_elements[$key];
    }
    return null;
  }

  /**
   * Gets all keys/indexes of the collection elements.
   *
   * @return array
   */
  public function getKeys() {
    return array_keys($this->_elements);
  }

  /**
   * Gets all elements.
   *
   * @return array
   */
  public function getValues() {
    return array_values($this->_elements);
  }

  /**
   * Returns the number of elements in the collection.
   *
   * Implementation of the Countable interface.
   *
   * @return integer The number of elements in the collection.
   */
  public function count() {
    return count($this->_elements);
  }

  /**
   * Adds/sets an element in the collection at the index / with the specified key.
   *
   * When the collection is a Map this is like put(key,value)/add(key,value).
   * When the collection is a List this is like add(position,value).
   *
   * @param mixed $key
   * @param mixed $value
   */
  public function set($key, $value) {
    $this->_elements[$key] = $value;
  }

  /**
   * Adds an element to the collection.
   *
   * @param mixed $value
   * @return boolean Always TRUE.
   */
  public function add($value) {
    $this->_elements[] = $value;
    return true;
  }

  /**
   * Checks whether the collection is empty.
   *
   * Note: This is preferable over count() == 0.
   *
   * @return boolean TRUE if the collection is empty, FALSE otherwise.
   */
  public function isEmpty() {
    return !$this->_elements;
  }

  /**
   * Gets an iterator for iterating over the elements in the collection.
   *
   * @return ArrayIterator
   */
  public function getIterator() {
    return new ArrayIterator($this->_elements);
  }

  /**
   * 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) {
    return new static(array_map($func, $this->_elements));
  }

  /**
   * 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) {
    return new static(array_filter($this->_elements, $p));
  }

  /**
   * Applies the given predicate p to all elements of this collection,
   * returning true, if the predicate yields true for all elements.
   *
   * @param Closure $p The predicate.
   * @return boolean TRUE, if the predicate yields TRUE for all elements, FALSE otherwise.
   */
  public function forAll(Closure $p) {
    foreach ($this->_elements as $key => $element) {
      if (!$p($key, $element)) {
        return false;
      }
    }
    return true;
  }

  /**
   * 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) {
    $coll1 = $coll2 = array();
    foreach ($this->_elements as $key => $element) {
      if ($p($key, $element)) {
        $coll1[$key] = $element;
      }
      else {
        $coll2[$key] = $element;
      }
    }
    return array(
      new static($coll1),
      new static($coll2),
    );
  }

  /**
   * Returns a string representation of this object.
   *
   * @return string
   */
  public function __toString() {
    return __CLASS__ . '@' . spl_object_hash($this);
  }

  /**
   * Clears the collection.
   */
  public function clear() {
    $this->_elements = array();
  }

  /**
   * Extract 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
   * @param int $length
   * @return array
   */
  public function slice($offset, $length = null) {
    return array_slice($this->_elements, $offset, $length, true);
  }

  /**
   * Select all elements from a selectable that match the criteria and
   * return a new collection containing these elements.
   *
   * @param  Criteria $criteria
   * @return Collection
   */
  public function matching(Criteria $criteria) {
    $expr = $criteria
      ->getWhereExpression();
    $filtered = $this->_elements;
    if ($expr) {
      $visitor = new ClosureExpressionVisitor();
      $filter = $visitor
        ->dispatch($expr);
      $filtered = array_filter($filtered, $filter);
    }
    if ($orderings = $criteria
      ->getOrderings()) {
      $next = null;
      foreach (array_reverse($orderings) as $field => $ordering) {
        $next = ClosureExpressionVisitor::sortByField($field, $ordering == 'DESC' ? -1 : 1, $next);
      }
      usort($filtered, $next);
    }
    $offset = $criteria
      ->getFirstResult();
    $length = $criteria
      ->getMaxResults();
    if ($offset || $length) {
      $filtered = array_slice($filtered, (int) $offset, $length);
    }
    return new static($filtered);
  }

}