<?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 LGPL. For more information, see

 * <http://www.doctrine-project.org>.

 */

namespace Doctrine\Common\Collections;

use Closure, ArrayIterator;

/**

 * 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

{

    /**

     * 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()

     */

    public function offsetExists($offset)

    {

        return $this->containsKey($offset);

    }

    /**

     * ArrayAccess implementation of offsetGet()

     *

     * @see get()

     */

    public function offsetGet($offset)

    {

        return $this->get($offset);

    }

    /**

     * ArrayAccess implementation of offsetGet()

     *

     * @see add()

     * @see set()

     */

    public function offsetSet($offset, $value)

    {

        if ( ! isset($offset)) {

            return $this->add($value);

        }

        return $this->set($offset, $value);

    }

    /**

     * ArrayAccess implementation of offsetUnset()

     *

     * @see remove()

     */

    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)

    {

        return in_array($element, $this->_elements, true);

    }

    /**

     * Tests for the existance 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 preferrable 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);

    }

}