Docs + coding standards.

lib/Cake/Test/Case/Utility/HashTest.php

@@ -17,7 +17,7 @@ App::uses('Hash', 'Utility');
 class HashTest extends CakeTestCase {
 
 	public static function articleData() {
-		return  array(
+		return array(
 			array(
 				'Article' => array(
 					'id' => '1',
@@ -225,7 +225,6 @@ class HashTest extends CakeTestCase {
 		$data = array('1' => array('1.1' => '1.1.1'), '2', '3' => array('3.1' => array('3.1.1' => '3.1.1.1')));
 		$result = Hash::dimensions($data);
 		$this->assertEquals($result, 2);
-
 	}
 
 /**
@@ -360,7 +359,6 @@ class HashTest extends CakeTestCase {
 		);
 		$this->assertEquals($expected, $result);
 
-
 		$b = array(
 			0 => array('name' => 'me'),
 			1 => array('name' => 'about')
@@ -377,7 +375,6 @@ class HashTest extends CakeTestCase {
 		$result = Hash::diff($a, $b);
 		$this->assertEquals($result, $b);
 
-
 		$a = array('name' => 'bob', 'address' => 'home');
 		$b = array();
 		$result = Hash::diff($a, $b);
@@ -478,7 +475,7 @@ class HashTest extends CakeTestCase {
 				'fields' => array('image_1_id', 'image_2_id', 'image_3_id', 'image_4_id', 'image_5_id')
 			)
 		);
-		$b =  array(
+		$b = array(
 			'Cacheable' => array('enabled' => false),
 			'Limit',
 			'Bindable',
@@ -1039,14 +1036,14 @@ class HashTest extends CakeTestCase {
  * @return void
  */
 	public function testSortString() {
-		$to_sort = array(
+		$toSort = array(
 			'four' => array('number' => 4, 'some' => 'foursome'),
 			'six' => array('number' => 6, 'some' => 'sixsome'),
 			'five' => array('number' => 5, 'some' => 'fivesome'),
 			'two' => array('number' => 2, 'some' => 'twosome'),
 			'three' => array('number' => 3, 'some' => 'threesome')
 		);
-		$sorted = Hash::sort($to_sort, '{s}.number', 'asc');
+		$sorted = Hash::sort($toSort, '{s}.number', 'asc');
 		$expected = array(
 			'two' => array('number' => 2, 'some' => 'twosome'),
 			'three' => array('number' => 3, 'some' => 'threesome'),
@@ -1290,7 +1287,6 @@ class HashTest extends CakeTestCase {
 		);
 		$this->assertEquals($expected, $result);
 
-
 		$result = Hash::combine($a, '{n}.User.id', '{n}.User.Data', '{n}.User.group_id');
 		$expected = array(
 			1 => array(
@@ -1450,7 +1446,7 @@ class HashTest extends CakeTestCase {
 	public function testMap() {
 		$data = self::articleData();
 
-		$result = Hash::map($data, '{n}.Article.id', array($this, '_mapCallback'));
+		$result = Hash::map($data, '{n}.Article.id', array($this, 'mapCallback'));
 		$expected = array(2, 4, 6, 8, 10);
 		$this->assertEquals($expected, $result);
 	}
@@ -1470,7 +1466,7 @@ class HashTest extends CakeTestCase {
 	public function testReduce() {
 		$data = self::articleData();
 
-		$result = Hash::reduce($data, '{n}.Article.id', array($this, '_reduceCallback'));
+		$result = Hash::reduce($data, '{n}.Article.id', array($this, 'reduceCallback'));
 		$this->assertEquals(15, $result);
 	}
 
@@ -1480,7 +1476,7 @@ class HashTest extends CakeTestCase {
  * @param mixed $value
  * @return mixed.
  */
-	public function _mapCallback($value) {
+	public function mapCallback($value) {
 		return $value * 2;
 	}
 
@@ -1491,7 +1487,7 @@ class HashTest extends CakeTestCase {
  * @param mixed $two
  * @return mixed.
  */
-	public function _reduceCallback($one, $two) {
+	public function reduceCallback($one, $two) {
 		return $one + $two;
 	}
 
@@ -1903,7 +1899,7 @@ class HashTest extends CakeTestCase {
 		);
 
 		$result = Hash::nest($input, array('idPath' => '{n}.id', 'parentPath' => '{n}.parent_id'));
-		foreach($result as &$row) {
+		foreach ($result as &$row) {
 			if (empty($row['children'])) {
 				unset($row['children']);
 			}
@@ -2009,7 +2005,7 @@ class HashTest extends CakeTestCase {
 		$this->assertEquals($result, $array1);
 
 		$result = Hash::mergeDiff($array1, $array2);
-		$this->assertEquals($result, $array1+$array2);
+		$this->assertEquals($result, $array1 + $array2);
 	}
 
 /**

lib/Cake/Utility/Hash.php

@@ -19,10 +19,10 @@ App::uses('String', 'Utility');
  * Library of array functions for manipulating and extracting data
  * from arrays or 'sets' of data.
  *
- * `Hash` provides an improved interface and more consistent and 
+ * `Hash` provides an improved interface, more consistent and
  * predictable set of features over `Set`.  While it lacks the spotty
  * support for pseudo Xpath, its more fully featured dot notation provides
- * the similar features in a more consistent way.
+ * similar features in a more consistent implementation.
  *
  * @package       Cake.Utility
  */
@@ -31,7 +31,7 @@ class Hash {
 /**
  * Get a single value specified by $path out of $data.
  * Does not support the full dot notation feature set,
- * but is faster for simple operations.
+ * but is faster for simple read operations.
  *
  * @param array $data Array of data to operate on.
  * @param mixed $path The path being searched for. Either a dot
@@ -63,10 +63,9 @@ class Hash {
  * The path expression is a dot separated expression, that can contain a set
  * of patterns and expressions:
  *
- * - `{n}` Matches any numeric key.
+ * - `{n}` Matches any numeric key, or integer.
  * - `{s}` Matches any string key.
- * - `[id]` Matches elements with an `id` index.
+ * - `Foo` Matches any key with the exact same value.
- * - `[id>2]` Matches elements that have an `id` index greater than 2.  
  *
  * There are a number of attribute operators:
  *
@@ -80,7 +79,7 @@ class Hash {
  * - `{n}.User.name` Get the name of every user in the set of users.
  * - `{n}.User[id]` Get the name of every user with an id key.
  * - `{n}.User[id>=2]` Get the name of every user with an id key greater than or equal to 2.
- * - `{n}.User[username=/^paul/]` Get User elements with username containing `^paul`.
+ * - `{n}.User[username=/^paul/]` Get User elements with username matching `^paul`.
  *
  * @param array $data The data to extract from.
  * @param string $path The path to extract.
@@ -94,7 +93,7 @@ class Hash {
 
 		// Simple paths.
 		if (!preg_match('/[{\[]/', $path)) {
-			return (array) self::get($data, $path);
+			return (array)self::get($data, $path);
 		}
 
 		if (strpos('[', $path) === false) {
@@ -107,7 +106,7 @@ class Hash {
 
 		$context = array($_key => array($data));
 
-		do  {
+		do {
 			$token = array_shift($tokens);
 			$next = array();
 
@@ -163,10 +162,10 @@ class Hash {
 	}
 
 /**
- * Checks whether or not $data matches the selector
+ * Checks whether or not $data matches the attribute patterns
  *
  * @param array $data Array of data to match.
- * @param string $selector The selector to match.
+ * @param string $selector The patterns to match.
  * @return boolean Fitness of expression.
  */
 	protected static function _matches(array $data, $selector) {
@@ -220,7 +219,8 @@ class Hash {
 	}
 
 /**
- * Insert $values into an array with the given $path.
+ * Insert $values into an array with the given $path. You can use
+ * `{n}` and `{s}` elements to insert $data multiple times.
  *
  * @param array $data The data to insert into.
  * @param string $path The path to insert at.
@@ -289,6 +289,8 @@ class Hash {
 
 /**
  * Remove data matching $path from the $data array.
+ * You can use `{n}` and `{s}` to remove multiple elements
+ * from $data.
  *
  * @param array $data The data to operate on
  * @param string $path A path expression to use to remove.
@@ -313,7 +315,6 @@ class Hash {
 		return $data;
 	}
 
-
 /**
  * Creates an associative array using `$keyPath` as the path to build its keys, and optionally
  * `$valuePath` as path to get the values. If `$valuePath` is not specified, all values will be initialized
@@ -411,10 +412,10 @@ class Hash {
 		$data = $extracted;
 		$count = count($data[0]);
 
-		$count2 = count($data);
+		$countTwo = count($data);
 		for ($j = 0; $j < $count; $j++) {
 			$args = array();
-			for ($i = 0; $i < $count2; $i++) {
+			for ($i = 0; $i < $countTwo; $i++) {
 				if (array_key_exists($j, $data[$i])) {
 					$args[] = $data[$i][$j];
 				}
@@ -600,7 +601,7 @@ class Hash {
 		$return = current($args);
 
 		while (($arg = next($args)) !== false) {
-			foreach ((array)$arg as $key => $val)	 {
+			foreach ((array)$arg as $key => $val) {
 				if (!empty($return[$key]) && is_array($return[$key]) && is_array($val)) {
 					$return[$key] = self::merge($return[$key], $val);
 				} elseif (is_int($key)) {
@@ -626,7 +627,7 @@ class Hash {
 		}
 		$values = array_values($data);
 		$str = implode('', $values);
-		return (bool) ctype_digit($str);
+		return (bool)ctype_digit($str);
 	}
 
 /**