Collection

collection.php

<?php

/**
 * Design namespace. This namespace is meant for abstract concepts and in most
 * cases simply just interfaces that in someway structures the general design
 * used in the core components.
 *
 * @package    Atom
 * @subpackage Library
 */
namespace Atom\Design;

// Aliasing rules
use \Atom\Design\Enumerable as Enum;

/**
 * Collection Class
 *
 * @package    Atom
 * @subpackage Library
 */
class Collection extends Enum {

	/**
	 * Class Constructor
	 *
	 * @param    array    Array for enumeration
	 * @return   void
	 */
	public function __construct(array $enumerable = array())
	{
		$this->enumerable = $enumerable;
	}

	/**
	 * Add an item to the enumerable array
	 *
	 * @param     mixed     Item(s) to add to the collection
	 * @param     boolean   Prepend the item to the collection
	 * @return    void
	 */
	public function add($items, $prepend = false)
	{
		$items = (array) $items;

		foreach($items as $item)
		{
			if($prepend)
			{
				array_shift($this->enumerable, $item);
				continue;
			}
			$this->enumerable []= $item;
		}
	}

	/**
	 * Alias for Collection::add($item, true)
	 *
	 * @see \Atom\Design\Collection::add()
	 */
	public function prepend($items)
	{
		$this->add($items, true);
	}

	/**
	 * Remove an item from the collection array
	 *
	 * @param     mixed     Item(s) to remove from the collection
	 * @return    void
	 */
	public function remove($offsets)
	{
		$offsets = (array) $offsets;

		foreach($offsets as $offset)
		{
			$this->offsetUnset($offset);
		}
	}

	/**
	 * Return the first entry in the collection array, alternatively returning
	 * the first entry to match $lambda if it is supplied.
	 *
	 * @param     \Closure     Used to evaluate enum values, returns boolean
	 * @return    mixed        The first value to find or match
	 */
	public function first($lambda = null)
	{
		$lambda === null and $lambda = function() { return true; };

		$this->rewind();

		return $this->find($lambda);
	}

	/**
	 * Get an array of this collections array keys
	 *
	 * @return    array     Array keys for this collection
	 */
	public function keys()
	{
		return array_keys($this->enumerable);
	}

	/**
	 * Get an array of this collections array values
	 *
	 * @return    array     Array values for this collection
	 */
	public function values()
	{
		return array_values($this->enumerable);
	}

	/**
	 * Convert the collection array to a different format using Atom's
	 * format classes.
	 *
	 * @param     string     Formatter to use
	 * @param     mixed      Flags for the selected formatter
	 * @return    mixed      Formatter version of the collection array
	 */
	public function to($format, $flags = null)
	{
		$formatter = new \Atom\Format($format, $this->enumerable, $flags);

		return $formatter->data;
	}
}

/* End of file: collection.php */

enumerable.php

<?php

/**
 * Design namespace. This namespace is meant for abstract concepts and in most
 * cases simply just interfaces that in someway structures the general design
 * used in the core components.
 *
 * @package    Atom
 * @subpackage Library
 */
namespace Atom\Design;

/**
 * Enumerable Class
 *
 * The enumerable class is meant to provide more functionality to array's and
 * objects in PHP. It can be used directly, or by child classes to implement
 * flexible and powerful array testing and manipulation methods.
 *
 * @package    Atom
 * @subpackage Library
 */
class Enumerable implements \Countable, \ArrayAccess, \Iterator{

	/**
	 * Array set for enumeration
	 *
	 * @var    array
	 */
	protected $enumerable;

	/**
	 * Class Constructor
	 *
	 * @param    array    Array for enumeration
	 * @return   void
	 */
	public function __construct(array $enumerable = array())
	{
		$this->enumerable = $enumerable;
	}

	/**
	 * Evaluate enum to see if ANY values match against the lambda.
	 *
	 * Example lambda, checks for numeric values:
	 * <code>
	 *     function($value) { return is_numeric($value); }
	 * </code>
	 *
	 * @param    \Closure     Used to evaluate enum elements, returns boolean
	 * @return   boolean      True if ANY match is found.
	 */
	public function any($lambda)
	{
		foreach($this as $value)
		{
			if($lambda($value))
			{
				return true;
			}
		}

		return false;
	}

	/**
	 * Evaluate enum to see if ALL values match against the lambda.
	 *
	 * Example lambda, checks for numeric values:
	 * <code>
	 *     function($value) { return is_numeric($value); }
	 * </code>
	 *
	 * @param    \Closure     Used to evaluate enum elements, returns boolean
	 * @return   boolean      True if ALL values match
	 */
	public function all($lambda)
	{
		foreach($this as $value)
		{
			if(!$lambda($value))
			{
				return false;
			}
		}
		
		return true;
	}

	/**
	 * Get an array that corresponds to enum, with boolean values depending
	 * on how lambda evaluated against the value.
	 *
	 * @param     \Closure     Used to evaluate enum values, returns boolean
	 * @return    array        Array of boolean values
	 */
	public function collect($lambda)
	{
		return array_map($lambda, $this->enumerable);
	}

	/**
	 * Find ONE element based on lambda evaluation. The first value to match
	 * will be returned. If no values match, the default value is returned.
	 *
	 * @param     \Closure     Used to evaluate enum values, returns boolean
	 * @param     mixed        Default value to return
	 * @return    mixed
	 */
	public function find($lambda, $default = null)
	{
		foreach($this as $value)
		{
			if($lambda($value))
			{
				return $value;
			}
		}

		return $default;
	}

	/**
	 * Find ALL values based on lambda evaluation.
	 *
	 * @param     \Closure     Used to evaluate enum values, returns boolean
	 * @return    array        Matching values
	 */
	public function find_all($lambda)
	{
		return array_values(array_filter($this->enumerable, $lambda));
	}

	/**
	 * Perform lambda against each enum value.
	 *
	 * @param     \Closure     Used to evaluate enum values, returns boolean
	 * @return    void
	 */
	public function each($lambda)
	{
		array_walk($this->enumerable, $lambda);
	}

	/**
	 * Perform lambda against each enum value, include the enum value's index
	 *
	 * @param     \Closure     Used to evaluate enum values, returns boolean
	 * @return    void
	 */
	public function each_with_index($lambda)
	{
		foreach($this as $index => $value)
		{
			$lambda($value, $index);
		}
	}

	/**
	 * Check for an object's existence within the enum values. "Object" in this
	 * context means any value or construct that can be tested for equality in PHP.
	 *
	 * @param    mixed       Object to search for
	 * @return   boolean     True if $obj was found within enum values
	 */
	public function member($obj)
	{
		return in_array($obj, $this->enumerable);
	}

	/**
	 * Convert all enum values into a single value.
	 *
	 * @param     \Closure     Used to evaluate enum values, returns boolean
	 * @return    mixed
	 */
	public function combine($lambda)
	{
		$shift  = array_shift($this->enumerable);
		$result = array_reduce($this->enumerable, $lambda, $shift);
		array_unshift($this->enumerable, $shift);
		
		return $result;
	}

	/**
	 * Run a grep search against enum values
	 *
	 * @param    string     Grep regular expression
	 * @return   array      Array of matched values
	 */
	public function grep($pattern, $lambda = null)
	{
		$match = preg_grep($pattern, $this->enumerable);
		
		return ($lambda === null) ? $match : array_map($lambda, $match);
	}

	/**
	 * Get an array of accepted values, with the acceptance based off of
	 * the given lambda's return boolean value.
	 *
	 * @param     \Closure     Used to evaluate enum values, returns boolean
	 * @return    array        Array of accepted values
	 */
	public function accept($lambda)
	{
		$accept = array();

		foreach($this as $value)
		{
			if($lambda($value))
			{
				$accept []= $value;
			}
		}

		return $accept;
	}

	/**
	 * Get an array of rejected values, with the rejection based off of
	 * the given lambda's return boolean value.
	 *
	 * @param     \Closure     Used to evaluate enum values, returns boolean
	 * @return    array        Array of rejected values
	 */
	public function reject($lambda)
	{
		$reject = array();

		foreach($this as $value)
		{
			if(!$lambda($value))
			{
				$reject []= $value;
			}
		}

		return $reject;
	}

	public function sort($lambda = null)
	{
		$sort = $this->enumerable;

		return ($lambda === null) ? sort($sort) : sort($sort, $lambda);
	}

	public function sort_by($lambda)
	{
		foreach($this as $value)
		{
			$sort[$value] = $lambda($value);
		}

		asort($sort);

		return array_values(array_flip($sort));
	}

	/**
	 * Return the highest value in the enumerable array
	 *
	 * @see       http://us.php.net/manual/en/function.max.php
	 *
	 * @param     \Closure     Used to evaluate enum values, returns boolean
	 * @return    mixed        Highest value in enumerable array
	 */
	public function max($lambda = null)
	{
		return $lambda === null ? max($this->enumerable) : end($this->sort($lambda));
	}

	/**
	 * Return the lowest value in the enumerable array
	 *
	 * @see       http://us.php.net/manual/en/function.min.php
	 *
	 * @param     \Closure     Used to evaluate enum values, returns boolean
	 * @return    mixed        Lowest value in enumerable array
	 */
	public function min($lambda = null)
	{
		return $lambda === null ? min($this->enumerable) : current($this->sort($lambda));
	}

	/**
	 * Return Enumerable instance as an array
	 *
	 * @return    array     Enumerable array
	 */
	public function to_array()
	{
		return $this->enumerable;
	}

	/**
	 * Return Enumerable instance as an object
	 *
	 * @return    object     Enumerable array converted to an object
	 */
	public function to_object()
	{
		return \Atom\Arr::to_object($this->enumerable);
	}

	/**
	 * ArrayAccess methods
	 */
	public function offsetExists($offset) { return isset($this->enumerable[$offset]); }
	public function offsetGet($offset) { return $this->enumerable[$offset]; }
	public function offsetSet($offset, $value) { $this->enumerable[$offset] = $value; }
	public function offsetUnset($offset) { unset($this->enumerable[$offset]); }

	/**
	 * Countable methods
	 */
	public function count() { return count($this->enumerable); }

	/**
	 * Iterator methods
	 */
	public function current() { return current($this->enumerable); }
	public function key() { return key($this->enumerable); }
	public function next() { return next($this->enumerable); }
	public function rewind() { return reset($this->enumerable); }
	public function valid() { return key($this->enumerable) !== null; }
}

/* End of file: enumerable */