Introduce "$.contains"

From [the jQuery API docs on
$.contain()](http://api.jquery.com/jQuery.contains/)

> Description: Check to see if a DOM element is within another DOM element.
>
>     jQuery.contains( container, contained )
>
> - **container** The DOM element that may contain the other element.
> - **contained** The DOM element that may be contained by the other element.
>
> **Note:** The first argument *must* be a DOM element, not a jQuery object or
> plain JavaScript object.

Add additional fixture to more thoroughly test the logic for nested structures.

Add to project documentation.

Readme.md

@@ -507,6 +507,9 @@ $.dom()
 //   }]
 ```
 
+#### $.contains( container, contained )
+Checks to see if the `contained` DOM element is a descendent of the `container` DOM element.
+
 #### $.isArray( array )
 Checks to see the passed argument is an array.
 

lib/static.js

@@ -71,3 +71,25 @@ var text = exports.text = function(elems) {
 var root = exports.root = function() {
   return this(this._root);
 };
+
+/**
+ * $.contains()
+ */
+var contains = exports.contains = function(container, contained) {
+
+  // According to the jQuery API, an element does not "contain" itself
+  if (contained === container) {
+    return false;
+  }
+
+  // Step up the descendents, stopping when the root element is reached
+  // (signaled by `.parent` returning a reference to the same object)
+  while (contained && contained !== contained.parent) {
+    contained = contained.parent;
+    if (contained === container) {
+      return true;
+    }
+  }
+
+  return false;
+};

test/fixtures.js

@@ -12,3 +12,10 @@ exports.vegetables = [
     '<li>Sweetcorn</li>',
   '</ul>'
 ].join('');
+
+exports.food = [
+  '<ul id="food">',
+    exports.fruits,
+    exports.vegetables,
+  '</ul>'
+].join('');

test/utilities.js

@@ -0,0 +1,33 @@
+var expect = require('expect.js'),
+    $ = require('../'),
+    food = require('./fixtures').food;
+
+describe('utility methods', function() {
+
+  describe('.contains', function() {
+
+    it('(container, contained) : should correctly detect the provided element', function() {
+      var $food = $(food);
+      var $fruits = $food.find('#fruits');
+      var $apple = $fruits.find('.apple');
+
+      expect($.contains($food[0], $fruits[0])).to.equal(true);
+      expect($.contains($food[0], $apple[0])).to.equal(true);
+    });
+
+    it('(container, other) : should not detect elements that are not contained', function() {
+      var $food = $(food);
+      var $fruits = $food.find('#fruits');
+      var $vegetables = $food.find('#vegetables');
+      var $apple = $fruits.find('.apple');
+
+      expect($.contains($vegetables[0], $apple[0])).to.equal(false);
+      expect($.contains($fruits[0], $vegetables[0])).to.equal(false);
+      expect($.contains($vegetables[0], $fruits[0])).to.equal(false);
+      expect($.contains($fruits[0], $fruits[0])).to.equal(false);
+      expect($.contains($vegetables[0], $vegetables[0])).to.equal(false);
+    });
+
+  });
+
+});