From 3a082fd3d6cb2e72612d51b9d8e54e93effb93eb Mon Sep 17 00:00:00 2001
From: Derek Jones <derek.jones@ellislab.com>
Date: Thu, 7 Oct 2010 09:38:55 -0500
Subject: added elements() to the Array Helper to return elements from an array
 with specified keys only.  Differs from array_intersect_assoc() in that a
 default value can be provided for keys that do not exist in the supplied
 array

---
 system/helpers/array_helper.php      | 40 ++++++++++++++++++++++++++++
 user_guide/changelog.html            |  1 +
 user_guide/helpers/array_helper.html | 51 ++++++++++++++++++++++++++++++++++++
 3 files changed, 92 insertions(+)

diff --git a/system/helpers/array_helper.php b/system/helpers/array_helper.php
index bd30b7c16..447ee1aa4 100644
--- a/system/helpers/array_helper.php
+++ b/system/helpers/array_helper.php
@@ -73,6 +73,46 @@ if ( ! function_exists('random_element'))
 	}
 }
 
+// --------------------------------------------------------------------
+
+/**
+ * Elements
+ *
+ * Returns only the array items specified.  Will return a default value if
+ * it is not set.
+ *
+ * @access	public
+ * @param	array
+ * @param	array
+ * @param	mixed
+ * @return	mixed	depends on what the array contains
+ */
+if ( ! function_exists('elements'))
+{
+	function elements($items, $array, $default = FALSE)
+	{
+		$return = array();
+		
+		if ( ! is_array($items))
+		{
+			$items = array($items);
+		}
+		
+		foreach ($items as $item)
+		{
+			if (isset($array[$item]))
+			{
+				$return[$item] = $array[$item];
+			}
+			else
+			{
+				$return[$item] = $default;
+			}
+		}
+
+		return $return;
+	}
+}
 
 /* End of file array_helper.php */
 /* Location: ./system/helpers/array_helper.php */
\ No newline at end of file
diff --git a/user_guide/changelog.html b/user_guide/changelog.html
index 8a275dda2..8c052572a 100644
--- a/user_guide/changelog.html
+++ b/user_guide/changelog.html
@@ -139,6 +139,7 @@ Hg Tag: </p>
 			<li>If CSRF is enabled in the application config file, <kbd>form_open()</kbd> will automatically insert it as a hidden field.</li>
 			<li>Added <kbd>sanitize_filename()</kbd> into the <a href="./helpers/security_helper.html">Security helper</a>.</li>
 			<li>Added <kbd>ellipsize()</kbd> to the <a href="./helpers/text_helper.html">Text Helper</a></li>
+			<li>Added <kbd>elements()</kbd> to the <a href="./helpers/array_helper.html">Array Helper</a></li>
 		</ul>
 	</li>
 	<li>Other Changes
diff --git a/user_guide/helpers/array_helper.html b/user_guide/helpers/array_helper.html
index c0bdd78e3..6d95c4a5f 100644
--- a/user_guide/helpers/array_helper.html
+++ b/user_guide/helpers/array_helper.html
@@ -100,7 +100,58 @@ echo element('size', $array, NULL);
 echo random_element($quotes);</code>
 
 
+<h2>elements()</h2>
 
+<p>Lets you fetch a number of items from an array.  The function tests whether each of the array indices is set.  If an index does not exist
+it is set to FALSE, or whatever you've specified as the default value via the third parameter.  Example:</p>
+
+<code>
+$array = array(<br />
+&nbsp;&nbsp;&nbsp;&nbsp;'color' => 'red',<br />
+&nbsp;&nbsp;&nbsp;&nbsp;'shape' => 'round',<br />
+&nbsp;&nbsp;&nbsp;&nbsp;'radius' => '10',<br />
+&nbsp;&nbsp;&nbsp;&nbsp;'diameter' => '20'<br />
+);<br />
+<br />
+$my_shape = elements(array('color', 'shape', 'height'), $array);<br />
+</code>
+
+<p>The above will return the following array:</p>
+
+<code>
+array(<br />
+&nbsp;&nbsp;&nbsp;&nbsp;'color' => 'red',<br />
+&nbsp;&nbsp;&nbsp;&nbsp;'shape' => 'round',<br />
+&nbsp;&nbsp;&nbsp;&nbsp;'height' => FALSE<br />
+);
+</code>
+
+<p>You can set the third parameter to any default value you like:</p>
+
+<code>
+$my_shape = elements(array('color', 'shape', 'height'), $array, NULL);<br />
+</code>
+
+<p>The above will return the following array:</p>
+
+<code>
+array(<br />
+&nbsp;&nbsp;&nbsp;&nbsp;'color' => 'red',<br />
+&nbsp;&nbsp;&nbsp;&nbsp;'shape' => 'round',<br />
+&nbsp;&nbsp;&nbsp;&nbsp;'height' => NULL<br />
+);
+</code>
+
+<p>This is useful when sending the <kbd>$_POST</kbd> array to one of your Models.  This prevents users from
+sending additional POST data to be entered into your tables:</p>
+
+<code>
+$this->load->model('post_model');<br />
+<br />
+$this->post_model->update(elements(array('id', 'title', 'content'), $_POST));
+</code>
+
+<p>This ensures that only the id, title and content fields are sent to be updated.</p>
 
 </div>
 <!-- END CONTENT -->
-- 
cgit v1.2.3-24-g4f1b