Skip to content

Commit

Permalink
Documentation complete for Hash
Browse files Browse the repository at this point in the history
  • Loading branch information
@KrisJordan
KrisJordan committed Feb 15, 2010
1 parent c2fb782 commit 8febbad
Show file tree
Hide file tree
Showing 3 changed files with 171 additions and 91 deletions.
251 changes: 163 additions & 88 deletions lib/Recess/Core/Hash.php
View file
Expand Up @@ -3,13 +3,8 @@
/** @addtogroup Core *//** @{ */

/**
* An object-oriented PHP array with higher-order methods like map(), each(), & filter().
* Hash implements IHash (which extends ArrayAccess) so it can be used as an array.
* IHash also requires higher-order methods:
* - map()
* - reduce()
* - each()
* - filter()
* An object-oriented wrapper around PHP's array with higher-order methods like map(),
* each(), & filter().
*
* @include examples/Recess/Core/Hash.php
*
Expand All @@ -24,16 +19,15 @@
class Hash implements IHash {
/** @} */

/** @var array The PHP array the Hash wraps. */
protected $elements;

/**
* Hashes can be constructed in two ways, with a list of arguments or
* with a first-class array.
*
* @code
* new Hash(array('key'=>'value'));
* new Hash(1,2,3,4);
* $hash = new Hash(array('key'=>'value'));
* $hash = new Hash(1,2,3,4);
* @endcode
*
* @param $elements or list
Expand All @@ -43,150 +37,231 @@ function __construct($elements = array()) {
$this->elements = isset($arguments[1]) || !is_array($elements) ?
$arguments : $elements;
}

/**
* Count all elements elements in a Hash with <code>count($hash)</code>.
* Implementation for the SPL <code>Countable</code> interface.
*
* @code
* $hash = new Hash(1,2,3,4);
* echo count($hash);
* //> 4
* @endcode
*
* @see http://php.net/manual/class.countable.php
*
* @return int Number of elements in the Hash.
*/
function count() {
return count($this->elements);
}

/**
* Return the current element with <code>current($hash)</code>.
* Implementation for the SPL <code>Iterator</code> interface.
* Also used internally during a <code>foreach</code> over elements in the Hash.
*
* @see Iterator::current http://php.net/manual/iterator.current.php
*
* @return mixed The value of the Hash's internal pointer points to.
*/
function current() {
return current($this->elements);
}

/**
* Convert the Hash into a PHP array.
* @return array
* Invoke a callable on each element of the Hash.
*
* @code
* $hash = new Hash(1,2,3,4);
* $hash->each(function($elem) { echo "-$elem-"; });
* //> -1--2--3--4-
* @endcode
*
* @param $callable
* @return Hash self referential for chaining.
*/
function toArray() {
return $this->elements;
function each($callable) {
each($this->elements, $callable);
return $this;
}

/**
* Map a callable over the values in the hash.
* Return a Hash containing of the elements of the original Hash
* who, when passed to the filter callable, return true.
*
* @code
* $hash = new Hash(1,2,3,4);
* $evens = $hash->filter(function($x) { return $x % 2 === 0; }));
* var_export($evens);
* //> array(2,4)
* @endcode
*
* @param $callable
* @return Hash
*/
function map($callable) {
return new Hash(map($this->elements,$callable));
function filter($callable) {
return new Hash(filter($this->elements, $callable));
}

/**
* Reduce the values of a hash to a single value using a callable.
* Return an external Iterator to traverse the elements of the Hash. Implementation
* for PHP's IteratorAggregate interface.
*
* @param $callable
* @param $identity The value to use if the Hash contains 1 or less element.
* @return varies
* @see IteratorAggregate http://php.net/manual/class.iteratoraggregate.php
*
* @return Iterator http://php.net/manual/class.iterator.php
*/
function reduce($callable, $identity) {
return reduce($this->elements, $callable, $identity);
}
function getIterator() {
return new \ArrayIterator($this->elements);
}

/**
* Invoke a callable on each element of the hash.
* Return the key of the current element.
*
* @param $callable
* @return Hash self referential for chaining.
* @see Iterator::key http://php.net/manual/iterator.key.php
*
* @return scalar
*/
function each($callable) {
each($this->elements, $callable);
return $this;
}
function key() {
return key($this->elements);
}

/**
* Returns a new hash consisting of the elements of the old hash
* who, when passed to the callable, return true.
* Return a Hash containing the return values of $callable called on
* each element of the Hash.
*
* Example:
* @code
* $hash = new Hash(1,2,3,4);
* print_r($hash->filter(function($x) { return $x % 2 === 0; }));
* // array ( 2, 4 )
* $doubled = $hash->map(function($elem) { return $elem * 2; });
* var_export($doubled);
* //> array(2,4,6,8);
* @endcode
*
* @param $callable
* @return Hash
*/
function filter($callable) {
return new Hash(filter($this->elements, $callable));
function map($callable) {
return new Hash(map($this->elements,$callable));
}

/**
* Move forward to the next element.
*
* @see Iterator::next http://php.net/manual/iterator.next.php
*/
function next() {
next($this->elements);
}

/**
* Implementation of \ArrayAccess interface that enables:
* is_set($hash[0])
* Whether an offset exists. This method is executed when using isset() or empty().
*
* @code
* $hash = new Hash(1);
* echo isset($hash[0]) ? "t" : "f";
* //> t
* echo isset($hash[1]) ? "t" : "f";
* //> f
* @endcode
*
* @see \ArrayAccess::offsetExists
* @param $offset
* @return varies
* @see ArrayAccess::offsetExists http://php.net/manual/arrayaccess.offsetexists.php
* @param mixed $offset An offset to check for.
* @return boolean
*/
function offsetExists($offset) {
return isset($this->elements[$offset]);
}

/**
* Implementation of \ArrayAccess interface that enables:
* echo $hash[0];
* Return the value at the specified offset. This method is executed when chicking if offset is empty().
*
* @see \ArrayAccess::offsetGet
* @param $offset
* @return varies
* @see ArrayAccess::offsetGet http://php.net/manual/arrayaccess.offsetget.php
* @param mixed $offset The offset to retrieve.
* @return mixed
*/
function offsetGet($offset) {
return $this->elements[$offset];
}

/**
* Implementation of \ArrayAccess interface that enables:
* Assigns a value to the specified offset.
*
* @code
* $hash = new Hash();
* $hash[0] = 1;
* @endcode
*
* @see \ArrayAccess::offsetSet
* @param $offset
* @param $value
* @see ArrayAccess::offsetSet http://php.net/manual/arrayaccess.offsetset.php
* @param $offset The offset to assign the value to.
* @param $value The value to set.
*/
function offsetSet($offset, $value) {
$this->elements[$offset] = $value;
}

/**
* Implementation of \ArrayAccess interface that enables:
* Unset an offset.
*
* @code
* $hash = new Hash(1);
* unset($hash[0]);
* echo isset($hash[0]) ? 't' : 'f';
* //> f
* @endcode
*
* @see \ArrayAccess::offsetUnset
* @param $offset
* @see ArrayAccess::offsetUnset http://php.net/manual/arrayaccess.offsetunset.php
* @param $offset The offset to unset.
*/
function offsetUnset($offset) {
unset($this->elements[$offset]);
}
}

/**
* Implementation of \Countable interface that enables:
* count($hash);
*
* @see \Countable::count
*/
function count() {
return count($this->elements);
}

/** @see \Iterator::current */
function current() {
return current($this->elements);
/**
* Reduce the values of a hash to a single value using a callable.
*
* @code
* $hash = new Hash(1,2,3,4);
* $sum = $hash->reduce(function($a,$b){return $a + $b;},0);
* echo $sum;
* //> 10
* @endcode
*
* @param $callable The function combining elements of the hash.
* @param $identity The value to use if the Hash contains 1 or less element.
* @return mixed
*/
function reduce($callable, $identity) {
return reduce($this->elements, $callable, $identity);
}

/** @see \Iterator::key */
function key() {
return key($this->elements);
}

/** @see \Iterator::next */
function next() {
return next($this->elements);
}

/** @see \Iterator::rewind */
/**
* Rewind the internal pointer to the first element of the Hash.
*
* @see Iterator::rewind http://php.net/manual/iterator.rewind.php
*/
function rewind() {
return reset($this->elements);
}

/** @see \Iterator::valid */

/**
* Return the elements of a Hash as a native PHP array.
*
* @return array
*/
function toArray() {
return $this->elements;
}

/**
* Checks if the internal pointer's current position is valid. This method is called
* after rewind() and next() to check if the current position is valid.
*
* @see Iterator::valid http://php.net/manual/iterator.valid.php
*
* @return boolean
*/
function valid() {
return key($this->elements) !== NULL;
}

/* @see \IteratorAggregate::getIterator */
function getIterator() {
return new \ArrayIterator($this->elements);
}

}
7 changes: 7 additions & 0 deletions lib/Recess/Core/IHash.php
View file
Expand Up @@ -2,6 +2,13 @@
namespace Recess\Core;
/** @addtogroup Core *//** @{ */

/**
*
* @see ArrayAccess http://php.net/manual/class.arrayaccess.php
* @see Countable http://php.net/manual/class.countable.php
* @see Iterator http://php.net/manual/class.iterator.php
* @see IteratorAggregate http://php.net/manual/class.iteratoraggregate.php
*/
interface IHash extends \ArrayAccess, \Countable, \Iterator, \IteratorAggregate {
/** @} */

Expand Down
4 changes: 1 addition & 3 deletions lib/Recess/Core/functions.php
View file
Expand Up @@ -74,9 +74,7 @@ function map($array, $callable) {
* will be returned.
*
* @code
* var_export(
* reduce(array(1,2,3,4), function($x,$y) { return $x + $y; }, 1)
* );
* echo reduce(array(1,2,3,4), function($x,$y) { return $x + $y; }, 1);
* //> 10
* @endcode
*
Expand Down

0 comments on commit 8febbad

Please sign in to comment.