Implement Cheerio#not

Closes cheeriojs#566.

Readme.md

@@ -427,6 +427,27 @@ $('li').filter(function(i, el) {
 //=> orange
 ```
 
+#### .not( selector ) <br /> .not( selection ) <br /> .not( element ) <br /> .not( function(index, elem) )
+
+Remove elements from the set of matched elements. Given a jQuery object that represents a set of DOM elements, the `.not()` method constructs a new jQuery object from a subset of the matching elements. The supplied selector is tested against each element; the elements that don't match the selector will be included in the result. The `.not()` method can take a function as its argument in the same way that `.filter()` does. Elements for which the function returns true are excluded from the filtered set; all other elements are included.
+
+Selector:
+
+```js
+$('li').not('.apple').length;
+//=> 2
+```
+
+Function:
+
+```js
+$('li').filter(function(i, el) {
+  // this === el
+  return $(this).attr('class') === 'orange';
+}).length;
+//=> 2
+```
+
 #### .first()
 Will select the first element of a cheerio object
 

lib/api/traversing.js

@@ -302,29 +302,32 @@ exports.map = function(fn) {
   }, []));
 };
 
-exports.filter = function(match, container) {
-  container = container || this;
-
-  var make = _.bind(container._make, container);
-  var filterFn;
-
-  if (typeof match === 'string') {
-    filterFn = select.compile(match, container.options);
-  } else if (typeof match === 'function') {
-    filterFn = function(el, i) {
-      return match.call(el, i, el);
-    };
-  } else if (match.cheerio) {
-    filterFn = match.is.bind(match);
-  } else {
-    filterFn = function(el) {
-      return match === el;
-    };
-  }
+var makeFilterMethod = function(filterFn) {
+  return function(match, container) {
+    var testFn;
+    container = container || this;
+
+    if (typeof match === 'string') {
+      testFn = select.compile(match, container.options);
+    } else if (typeof match === 'function') {
+      testFn = function(el, i) {
+        return match.call(el, i, el);
+      };
+    } else if (match.cheerio) {
+      testFn = match.is.bind(match);
+    } else {
+      testFn = function(el) {
+        return match === el;
+      };
+    }
 
-  return make(_.filter(this, filterFn));
+    return container._make(filterFn(this, testFn));
+  };
 };
 
+exports.filter = makeFilterMethod(_.filter);
+exports.not = makeFilterMethod(_.reject);
+
 exports.first = function() {
   return this.length > 1 ? this._make(this[0]) : this;
 };

test/api.traversing.js

@@ -771,6 +771,60 @@ describe('$(...)', function() {
     });
   });
 
+  describe('.not', function() {
+    it('(selector) : should reduce the set of matched elements to those that do not match the selector', function() {
+      var $fruits = $('li');
+
+      var $notPear = $fruits.not('.pear');
+
+      expect($notPear).to.have.length(2);
+      expect($notPear[0]).to.be($fruits[0]);
+      expect($notPear[1]).to.be($fruits[1]);
+    });
+
+    it('(selector) : should not consider nested elements', function() {
+      var lis = $('#fruits').not('li');
+      expect(lis).to.have.length(1);
+    });
+
+    it('(selection) : should reduce the set of matched elements to those that are mot contained in the provided selection', function() {
+      var $fruits = $('li');
+      var $orange = $('.orange');
+
+      var $notOrange = $fruits.not($orange);
+
+      expect($notOrange).to.have.length(2);
+      expect($notOrange[0]).to.be($fruits[0]);
+      expect($notOrange[1]).to.be($fruits[2]);
+    });
+
+    it('(element) : should reduce the set of matched elements to those that specified directly', function() {
+      var $fruits = $('li');
+      var apple = $('.apple')[0];
+
+      var $notApple = $fruits.not(apple);
+
+      expect($notApple).to.have.length(2);
+      expect($notApple[0]).to.be($fruits[1]);
+      expect($notApple[1]).to.be($fruits[2]);
+    });
+
+    it('(fn) : should reduce the set of matched elements to those that do not pass the function\'s test', function() {
+      var $fruits = $('li');
+
+      var $notOrange = $fruits.not(function(i, el) {
+        expect(this).to.be(el);
+        expect(el.name).to.be('li');
+        expect(i).to.be.a('number');
+        return $(this).attr('class') === 'orange';
+      });
+
+      expect($notOrange).to.have.length(2);
+      expect($notOrange[0]).to.be($fruits[0]);
+      expect($notOrange[1]).to.be($fruits[2]);
+    });
+  });
+
   describe('.first', function() {
 
     it('() : should return the first item', function() {