Merge pull request #415 from jugglinmike/get

Implement `$.fn.get`

Readme.md

@@ -442,6 +442,22 @@ $('li').eq(-1).text()
 //=> Pear
 ```
 
+#### .get( [i] )
+
+Retrieve the DOM elements matched by the Cheerio object. If an index is specified, retrieve one of the elements matched by the Cheerio object:
+
+```js
+$('li').get(0).name
+//=> li
+```
+
+If no index is specified, retrieve all elements matched by the Cheerio object:
+
+```js
+$('li').get().length
+//=> 3
+```
+
 #### .end()
 End the most recent filtering operation in the current chain and return the set of matched elements to its previous state.
 
@@ -608,14 +624,6 @@ $.xml()
 ### Miscellaneous
 DOM element methods that don't fit anywhere else
 
-#### .toArray()
-Retrieve all the DOM elements contained in the jQuery set, as an array.
-
-```js
-$('li').toArray()
-//=> [ {...}, {...}, {...} ]
-```
-
 #### .clone() ####
 Clone the cheerio object.
 

lib/api/manipulation.js

@@ -13,7 +13,7 @@ var makeDomArray = function(elem) {
   if (elem == null) {
     return [];
   } else if (elem.cheerio) {
-    return elem.toArray();
+    return elem.get();
   } else if (_.isArray(elem)) {
     return _.flatten(elem.map(makeDomArray));
   } else if (_.isString(elem)) {
@@ -195,7 +195,7 @@ var html = exports.html = function(str) {
     return $.html(this[0].children);
   }
 
-  str = str.cheerio ? str.toArray() : evaluate(str);
+  str = str.cheerio ? str.get() : evaluate(str);
 
   domEach(this, function(i, el) {
     el.children = str;

lib/api/traversing.js

@@ -38,7 +38,7 @@ var parents = exports.parents = function(selector) {
   // When multiple DOM elements are in the original set, the resulting set will
   // be in *reverse* order of the original elements as well, with duplicates
   // removed.
-  this.toArray().reverse().forEach(function(elem) {
+  this.get().reverse().forEach(function(elem) {
     traverseParents(this, elem.parent, selector, Infinity)
       .forEach(function(node) {
         if (parentNodes.indexOf(node) === -1) {
@@ -109,9 +109,9 @@ var nextUntil = exports.nextUntil = function(selector, filterSelector) {
   var elems = [], untilNode, untilNodes;
 
   if (typeof selector === 'string') {
-    untilNode = select(selector, this.nextAll().toArray())[0];
+    untilNode = select(selector, this.nextAll().get())[0];
   } else if (selector && selector.cheerio) {
-    untilNodes = selector.toArray();
+    untilNodes = selector.get();
   } else if (selector) {
     untilNode = selector;
   }
@@ -171,9 +171,9 @@ var prevUntil = exports.prevUntil = function(selector, filterSelector) {
   var elems = [], untilNode, untilNodes;
 
   if (typeof selector === 'string') {
-    untilNode = select(selector, this.prevAll().toArray())[0];
+    untilNode = select(selector, this.prevAll().get())[0];
   } else if (selector && selector.cheerio) {
-    untilNodes = selector.toArray();
+    untilNodes = selector.get();
   } else if (selector) {
     untilNode = selector;
   }
@@ -287,6 +287,15 @@ var eq = exports.eq = function(i) {
   return this[i] ? this._make(this[i]) : this._make([]);
 };
 
+// Retrieve the DOM elements matched by the jQuery object.
+var get = exports.get = function(i) {
+  if (i == null) {
+    return Array.prototype.slice.call(this);
+  } else {
+    return this[i < 0 ? (this.length + i) : i];
+  }
+};
+
 var slice = exports.slice = function() {
   return this._make([].slice.apply(this, arguments));
 };

lib/cheerio.js

@@ -139,10 +139,12 @@ Cheerio.prototype._make = function(dom) {
 
 /**
  * Turn a cheerio object into an array
+ *
+ * @deprecated
  */
 
 Cheerio.prototype.toArray = function() {
-  return [].slice.call(this, 0);
+  return this.get();
 };
 
 /**

test/api.manipulation.js

@@ -57,7 +57,7 @@ describe('$(...)', function() {
     it('(Array) : should append all elements in the array', function() {
       var $fruits = $(fruits);
       var more = $('<li class="plum">Plum</li><li class="grape">Grape</li>')
-        .toArray();
+        .get();
       $fruits.append(more);
       expect($fruits.children(3).hasClass('plum')).to.be.ok();
       expect($fruits.children(4).hasClass('grape')).to.be.ok();
@@ -190,7 +190,7 @@ describe('$(...)', function() {
     it('(Array) : should add all elements in the array as inital children', function() {
       var $fruits = $(fruits);
       var more = $('<li class="plum">Plum</li><li class="grape">Grape</li>')
-        .toArray();
+        .get();
       $fruits.prepend(more);
       expect($fruits.children(0).hasClass('plum')).to.be.ok();
       expect($fruits.children(1).hasClass('grape')).to.be.ok();
@@ -296,7 +296,7 @@ describe('$(...)', function() {
     it('(Array) : should add all elements in the array as next sibling', function() {
       var $fruits = $(fruits);
       var more = $('<li class="plum">Plum</li><li class="grape">Grape</li>')
-        .toArray();
+        .get();
       $('.apple', $fruits).after(more);
       expect($fruits.children(1).hasClass('plum')).to.be.ok();
       expect($fruits.children(2).hasClass('grape')).to.be.ok();
@@ -438,7 +438,7 @@ describe('$(...)', function() {
     it('(Array) : should add all elements in the array as previous sibling', function() {
       var $fruits = $(fruits);
       var more = $('<li class="plum">Plum</li><li class="grape">Grape</li>')
-        .toArray();
+        .get();
       $('.apple', $fruits).before(more);
       expect($fruits.children(0).hasClass('plum')).to.be.ok();
       expect($fruits.children(1).hasClass('grape')).to.be.ok();
@@ -541,7 +541,7 @@ describe('$(...)', function() {
     it('(Array) : should replace one <li> tag with the elements in the array', function() {
       var $fruits = $(fruits);
       var more = $('<li class="plum">Plum</li><li class="grape">Grape</li>')
-        .toArray();
+        .get();
       $('.pear', $fruits).replaceWith(more);
 
       expect($fruits.children(2).hasClass('plum')).to.be.ok();
@@ -592,7 +592,7 @@ describe('$(...)', function() {
 
     it('(fn) : should invoke the callback with the correct argument and context', function() {
       var $fruits = $(fruits);
-      var origChildren = $fruits.children().toArray();
+      var origChildren = $fruits.children().get();
       var args = [];
       var thisValues = [];
 

test/api.traversing.js

@@ -579,7 +579,7 @@ describe('$(...)', function() {
         return [1, [3, 4]];
       });
 
-      expect($mapped.toArray()).to.eql([
+      expect($mapped.get()).to.eql([
         1, [3, 4],
         1, [3, 4],
         1, [3, 4]
@@ -593,7 +593,7 @@ describe('$(...)', function() {
         return [null, undefined];
       });
 
-      expect($mapped.toArray()).to.eql([
+      expect($mapped.get()).to.eql([
         null, undefined,
         null, undefined,
         null, undefined,
@@ -704,6 +704,35 @@ describe('$(...)', function() {
 
   });
 
+  describe('.get', function() {
+
+    it('(i) : should return the element at the specified index', function() {
+      var children = $(fruits).children();
+      expect(children.get(0)).to.be(children[0]);
+      expect(children.get(1)).to.be(children[1]);
+      expect(children.get(2)).to.be(children[2]);
+    });
+
+    it('(-1) : should return the element indexed from the end of the collection', function() {
+      var children = $(fruits).children();
+      expect(children.get(-1)).to.be(children[2]);
+      expect(children.get(-2)).to.be(children[1]);
+      expect(children.get(-3)).to.be(children[0]);
+    });
+
+    it('() : should return an array containing all of the collection', function() {
+      var children = $(fruits).children();
+      var all = children.get();
+      expect(Array.isArray(all)).to.be.ok();
+      expect(all).to.eql([
+        children[0],
+        children[1],
+        children[2]
+      ]);
+    });
+
+  });
+
   describe('.slice', function() {
 
     function getText(el) {