New: New cell based API methods

- New API methods:
  - cells( rowSelector, columnSelector, opts ) - Cell selector
  - cells( ... ).nodes() - Get the nodes for the selected cells
  - cells( ... ).data() - Get the data for the selected cells
  - cell( rowSelector, columnSelector, opts ) - Single cell selector
  - cell( ... ).node() - Get the cell node
  - cell( ... ).data() - Get the cell data

- There was a bug in `_selector_first` whereby it wasn't correctly
  reducing the set - was gatting away with it before, because it was
  reducing to a single element array, which has a toString() method
  which allowed it to appear to work for integers.

media/src/DataTables.js

@@ -117,6 +117,7 @@
 	require('api.rows.js');
 	require('api.row.js');
 	require('api.columns.js');
+	require('api.cells.js');
 	require('api.order.js');
 	require('api.search.js');
 	require('api.static.js');

media/src/api/api._selectors.js

@@ -106,21 +106,20 @@ var _range = function ( len )
 var _selector_first = function ( inst )
 {
 	// Reduce the API instance to the first item found
-	var found = false;
 	for ( var i=0, ien=inst.length ; i<ien ; i++ ) {
-		if ( ! found ) {
-			if ( inst[i].length > 0 ) {
-				inst[i].splice( 1, inst[i].length );
-				inst.context = [ inst.context[i] ];
+		if ( inst[i].length > 0 ) {
+			// Assign the first element to the first item in the instance
+			// and truncate the instance and context
+			inst[0] = inst[i][0];
+			inst.length = 1;
+			inst.context = [ inst.context[i] ];
 
-				found = true;
-			}
-		}
-		else {
-			inst[i].splice( 0, inst[i].length );
+			return inst;
 		}
 	}
 
+	// Not found - return an empty instance
+	inst.length = 0;
 	return inst;
 };
 

media/src/api/api.base.js

@@ -324,7 +324,7 @@ _Api.prototype = /** @lends DataTables.Api */{
 			a = [], ret,
 			i, ien, j, jen,
 			context = this.context,
-			rows, items,
+			rows, items, item,
 			selector = this.selector;
 
 		// Argument shifting
@@ -350,7 +350,7 @@ _Api.prototype = /** @lends DataTables.Api */{
 					a.push( ret );
 				}
 			}
-			else if ( type === 'column' || type === 'column-rows' || type === 'row' ) {
+			else if ( type === 'column' || type === 'column-rows' || type === 'row' || type === 'cell' ) {
 				// columns and rows share the same structure.
 				// 'this' is an array of column indexes for each context
 				items = this[i];
@@ -360,7 +360,14 @@ _Api.prototype = /** @lends DataTables.Api */{
 				}
 
 				for ( j=0, jen=items.length ; j<jen ; j++ ) {
-					ret = fn( context[i], items[j], i, j, rows );
+					item = items[j];
+
+					if ( type === 'cell' ) {
+						ret = fn( context[i], item.row, item.column, i, j );
+					}
+					else {
+						ret = fn( context[i], item, i, j, rows );
+					}
 
 					if ( ret !== undefined ) {
 						a.push( ret );

media/src/api/api.cells.js

@@ -0,0 +1,78 @@
+
+
+(/** @lends <global> */function() {
+
+var _api = DataTable.Api;
+
+
+_api.register( 'cells()', function ( rowSelector, columnSelector, opts ) {
+	var columns = this.columns( columnSelector, opts );
+	var rows = this.rows( rowSelector, opts );
+	var a, i, ien, j, jen;
+
+	return this.iterator( 'table', function ( settings, idx ) {
+		a = [];
+
+		for ( i=0, ien=rows[idx].length ; i<ien ; i++ ) {
+			for ( j=0, jen=columns[idx].length ; j<jen ; j++ ) {
+				a.push( {
+					row:    rows[idx][i],
+					column: columns[idx][j]
+				} );
+			}
+		}
+
+		return a;
+	} );
+} );
+
+
+_api.register( 'cells().nodes()', function () {
+	return this.iterator( true, 'cell', function ( settings, row, column ) {
+		return settings.aoData[ row ].anCells[ column ];
+	} );
+} );
+
+
+_api.register( 'cells().data()', function () {
+	return this.iterator( true, 'cell', function ( settings, row, column ) {
+		return _fnGetCellData( settings, row, column );
+	} );
+} );
+
+
+
+
+_api.register( 'cell()', function ( rowSelector, columnSelector, opts ) {
+	return _selector_first( this.cells( rowSelector, columnSelector, opts ) );
+} );
+
+
+_api.register( 'cell().node()', function () {
+	var ctx = this.context;
+
+	if ( ctx.length && this.length ) {
+		return ctx[0].aoData[ this[0].row ].anCells[ this[0].column ];
+	}
+	// undefined
+} );
+
+
+_api.register( 'cell().data()', function ( data ) {
+	var ctx = this.context;
+
+	if ( data === undefined ) {
+		// Get
+		return ctx.length && this.length ?
+			_fnGetCellData( ctx[0], this[0].row, this[0].column ) :
+			undefined;
+	}
+
+	// Set
+	// @todo
+} );
+
+
+
+}());
+

media/src/api/api.row.js

@@ -39,9 +39,11 @@ _api.register( 'row().cells()', function () {
 _api.register( 'row().data()', function ( data ) {
 	var ctx = this.context;
 
-	if ( ctx.length && this.length ) {
+	if ( data === undefined ) ) {
 		// Get
-		return ctx[0].aoData[ this[0] ]._aData;
+		return ctx.length && this.length ?
+			ctx[0].aoData[ this[0] ]._aData :
+			undefined;
 	}
 
 	// Set