New: tables() and tables().nodes() methods for the new API:

- tables() is a table selector and iterator that most other API methods
  will likely use.

- tables().nodes() gets the selected HTML table nodes.

- Documentation of these functions is rather incomplete. Not yet sure
  how to fully document them. Currently thinking of having seperate
  documentation, a bit like jQuery, which can be a lot more involved,
  rather than building it fromt he doc comments which might get rather
  long (they already are!).

media/js/jquery.dataTables.js

@@ -6776,7 +6776,7 @@
 	 *     ]
 	 *
 	 * @type {Array}
-	 * @internal
+	 * @ignore
 	 */
 	var _apiStruct = [];
 	
@@ -6785,7 +6785,7 @@
 	 * Api object reference.
 	 *
 	 * @type object
-	 * @internal
+	 * @ignore
 	 */
 	var _api;
 	
@@ -6794,7 +6794,7 @@
 	 * `Array.prototype` reference.
 	 *
 	 * @type object
-	 * @internal
+	 * @ignore
 	 */
 	var _arrayProto = Array.prototype;
 	
@@ -6816,26 +6816,26 @@
 	 *   * `node` - `TABLE` node which has already been formed into a DataTable.
 	 *   * `jQuery` - A jQuery object of `TABLE` nodes.
 	 *   * `object` - DataTables settings object
-	 * @return {array|object|null} Matching DataTables settings object, or an array
-	 *   of matching objects. `null` or `undefined` is returned if no matching
-	 *   DataTable is found.
-	 * @internal
+	 * @return {array|null} Matching DataTables settings objects. `null` or
+	 *   `undefined` is returned if no matching DataTable is found.
+	 * @ignore
 	 */
 	var _toSettings = function ( mixed )
 	{
 		var idx, jq;
-		var tables = $.map( DataTable.settings, function (el, i) {
+		var settings = DataTable.settings;
+		var tables = $.map( settings, function (el, i) {
 			return el.nTable;
 		} );
 	
 		if ( mixed.nTable && mixed.oApi ) {
 			// DataTables settings object
-			return mixed;
+			return [ mixed ];
 		}
 		else if ( mixed.nodeName && mixed.nodeName.toLowerCase() === 'table' ) {
 			// Table node
 			idx = $.inArray( mixed, tables );
-			return idx !== -1 ? tables[idx] : null;
+			return idx !== -1 ? [ settings[idx] ] : null;
 		}
 		else if ( typeof mixed === 'string' ) {
 			// jQuery selector
@@ -6847,9 +6847,9 @@
 		}
 	
 		if ( jq ) {
-			return jq.map( function(el, i) {
-				idx = $.inArray( el, tables );
-				return idx !== -1 ? tables[idx] : null;
+			return jq.map( function(i) {
+				idx = $.inArray( this, tables );
+				return idx !== -1 ? settings[idx] : null;
 			} );
 		}
 	};
@@ -6860,26 +6860,34 @@
 	 *
 	 * @param  {array} src Source array
 	 * @return {array} Array of unique items
-	 * @internal
+	 * @ignore
 	 */
 	var _unique = function ( src )
 	{
-		// Use an object to store values which have been added to the unique
-		// array. This allows us to avoid a second loop (indexOf) to determine
-		// if the value is already in the unique array at the cost of temporary
-		// memory allocation.
-		var a=[], o={}, val;
+		// A faster unique method is to use object keys to identify used values,
+		// but this doesn't work with arrays or objects, which we must also
+		// consider. See jsperf.com/compare-array-unique-versions/4 for more
+		// information.
+		var
+			out = [],
+			val,
+			i, ien=src.length,
+			j, k=0;
 	
-		for ( var i=0, ien=src.length ; i<ien ; i++ ) {
+		again: for ( i=0 ; i<ien ; i++ ) {
 			val = src[i];
 	
-			if ( o[ val ] === undefined ) {
-				a.push( val );
-				o[ val ] = true;
+			for ( j=0 ; j<k ; j++ ) {
+				if ( out[j] === val ) {
+					continue again;
+				}
 			}
+	
+			out.push( val );
+			k++;
 		}
 	
-		return a;
+		return out;
 	};
 	
 	
@@ -7255,6 +7263,108 @@
 	};
 	
 	
+	}());
+	
+	
+	
+	(/** @lends <global> */function() {
+	
+	var _api = DataTable.Api;
+	
+	/**
+	 * Selector for HTML tables. Apply the given selector to the give array of
+	 * DataTables settings objects.
+	 *
+	 * @param {string|integer} [selector] jQuery selector string or integer
+	 * @param  {array} Array of DataTables settings objects to be filtered
+	 * @return {array}
+	 * @ignore
+	 */
+	var _table_selector = function ( selector, a )
+	{
+		// Integer is used to pick out a table by index
+		if ( typeof selector === 'number' ) {
+			return [ a[ selector ] ];
+		}
+	
+		// Perform a jQuery selector on the table nodes
+		var nodes = $.map( a, function (el, i) {
+			return el.nTable;
+		} );
+	
+		return $(nodes)
+			.filter( selector )
+			.map( function (i) {
+				// Need to translate back from the table node to the settings
+				var idx = $.inArray( this, nodes );
+				return a[ idx ];
+			} )
+			.toArray();
+	};
+	
+	
+	/**
+	 * Context selector and iterator for the API's context (i.e. the tables the
+	 * API instance refers to.
+	 *
+	 * @name    DataTable.Api#tables
+	 * @param {string|integer} [selector] Selector to pick which tables the iterator
+	 *   should operate on. If not given, all tables in the current context are
+	 *   used. This can be given as a jQuery selector (for example `':gt(0)'`) to
+	 *   select multiple tables or as an integer to select a single table.
+	 * @param {function} [fn] Iterator function. Will be called for every table in
+	 *   the current context (once the selector has been applied, if one is given).
+	 *   The function is passed two parameters: 1. the DataTables settings object
+	 *   for the table in question and 2. the index of that table in the current
+	 *   context. The execution scope of the function is the API instance.
+	 * @returns {DataTable.Api} Returns a new API instance if a selector is given,
+	 *   or the callback function returns information from each loop. The
+	 *   information, if returned, is assigned to the API instance. Otherwise the
+	 *   original API instance is returned for chaining.
+	 */
+	_api.register( 'tables()', function ( selector, fn ) {
+		// Argument shifting
+		if ( typeof selector === 'function' ) {
+			fn = selector;
+			selector = undefined;
+		}
+	
+		var a = [];
+		var context = selector ?
+			_table_selector( selector, this.context ) :
+			this.context;
+	
+		if ( fn ) {
+			for ( var i=0, ien=context.length ; i<ien ; i++ ) {
+				var ret = fn.call( this, context[i], i );
+				if ( ret !== undefined ) {
+					a.push( ret );
+				}
+			}
+		}
+	
+		// A new instance is created if there was a selector specified, or if
+		// data was returned from the callback
+		var api = selector || a.length ?
+			new _api( context, a ) :
+			this;
+	
+		return api;
+	} );
+	
+	
+	/**
+	 * Get the DOM nodes for the `table` elements from the current API context.
+	 * @return {DataTable.Api} New Api instance containing the DOM nodes for the
+	 *   tables.
+	 */
+	_api.register( 'tables().nodes()', function () {
+		return this.tables( function ( settings, i ) {
+			return settings.nTable;
+		} );
+	} );
+	
+	
 	}());
 	
 	/**

media/src/DataTables.js

@@ -109,6 +109,7 @@
 	};
 
 	require('api.core.js');
+	require('api.table.js');
 	require('api.static.js');
 
 	/**

media/src/api/api.core.js

@@ -37,7 +37,7 @@
  *     ]
  *
  * @type {Array}
- * @internal
+ * @ignore
  */
 var _apiStruct = [];
 
@@ -46,7 +46,7 @@ var _apiStruct = [];
  * Api object reference.
  *
  * @type object
- * @internal
+ * @ignore
  */
 var _api;
 
@@ -55,7 +55,7 @@ var _api;
  * `Array.prototype` reference.
  *
  * @type object
- * @internal
+ * @ignore
  */
 var _arrayProto = Array.prototype;
 
@@ -77,26 +77,26 @@ var _arrayProto = Array.prototype;
  *   * `node` - `TABLE` node which has already been formed into a DataTable.
  *   * `jQuery` - A jQuery object of `TABLE` nodes.
  *   * `object` - DataTables settings object
- * @return {array|object|null} Matching DataTables settings object, or an array
- *   of matching objects. `null` or `undefined` is returned if no matching
- *   DataTable is found.
- * @internal
+ * @return {array|null} Matching DataTables settings objects. `null` or
+ *   `undefined` is returned if no matching DataTable is found.
+ * @ignore
  */
 var _toSettings = function ( mixed )
 {
 	var idx, jq;
-	var tables = $.map( DataTable.settings, function (el, i) {
+	var settings = DataTable.settings;
+	var tables = $.map( settings, function (el, i) {
 		return el.nTable;
 	} );
 
 	if ( mixed.nTable && mixed.oApi ) {
 		// DataTables settings object
-		return mixed;
+		return [ mixed ];
 	}
 	else if ( mixed.nodeName && mixed.nodeName.toLowerCase() === 'table' ) {
 		// Table node
 		idx = $.inArray( mixed, tables );
-		return idx !== -1 ? tables[idx] : null;
+		return idx !== -1 ? [ settings[idx] ] : null;
 	}
 	else if ( typeof mixed === 'string' ) {
 		// jQuery selector
@@ -108,9 +108,9 @@ var _toSettings = function ( mixed )
 	}
 
 	if ( jq ) {
-		return jq.map( function(el, i) {
-			idx = $.inArray( el, tables );
-			return idx !== -1 ? tables[idx] : null;
+		return jq.map( function(i) {
+			idx = $.inArray( this, tables );
+			return idx !== -1 ? settings[idx] : null;
 		} );
 	}
 };
@@ -121,26 +121,34 @@ var _toSettings = function ( mixed )
  *
  * @param  {array} src Source array
  * @return {array} Array of unique items
- * @internal
+ * @ignore
  */
 var _unique = function ( src )
 {
-	// Use an object to store values which have been added to the unique
-	// array. This allows us to avoid a second loop (indexOf) to determine
-	// if the value is already in the unique array at the cost of temporary
-	// memory allocation.
-	var a=[], o={}, val;
+	// A faster unique method is to use object keys to identify used values,
+	// but this doesn't work with arrays or objects, which we must also
+	// consider. See jsperf.com/compare-array-unique-versions/4 for more
+	// information.
+	var
+		out = [],
+		val,
+		i, ien=src.length,
+		j, k=0;
 
-	for ( var i=0, ien=src.length ; i<ien ; i++ ) {
+	again: for ( i=0 ; i<ien ; i++ ) {
 		val = src[i];
 
-		if ( o[ val ] === undefined ) {
-			a.push( val );
-			o[ val ] = true;
+		for ( j=0 ; j<k ; j++ ) {
+			if ( out[j] === val ) {
+				continue again;
+			}
 		}
+
+		out.push( val );
+		k++;
 	}
 
-	return a;
+	return out;
 };
 
 

media/src/api/api.table.js

@@ -0,0 +1,102 @@
+
+
+(/** @lends <global> */function() {
+
+var _api = DataTable.Api;
+
+/**
+ * Selector for HTML tables. Apply the given selector to the give array of
+ * DataTables settings objects.
+ *
+ * @param {string|integer} [selector] jQuery selector string or integer
+ * @param  {array} Array of DataTables settings objects to be filtered
+ * @return {array}
+ * @ignore
+ */
+var _table_selector = function ( selector, a )
+{
+	// Integer is used to pick out a table by index
+	if ( typeof selector === 'number' ) {
+		return [ a[ selector ] ];
+	}
+
+	// Perform a jQuery selector on the table nodes
+	var nodes = $.map( a, function (el, i) {
+		return el.nTable;
+	} );
+
+	return $(nodes)
+		.filter( selector )
+		.map( function (i) {
+			// Need to translate back from the table node to the settings
+			var idx = $.inArray( this, nodes );
+			return a[ idx ];
+		} )
+		.toArray();
+};
+
+
+/**
+ * Context selector and iterator for the API's context (i.e. the tables the
+ * API instance refers to.
+ *
+ * @name    DataTable.Api#tables
+ * @param {string|integer} [selector] Selector to pick which tables the iterator
+ *   should operate on. If not given, all tables in the current context are
+ *   used. This can be given as a jQuery selector (for example `':gt(0)'`) to
+ *   select multiple tables or as an integer to select a single table.
+ * @param {function} [fn] Iterator function. Will be called for every table in
+ *   the current context (once the selector has been applied, if one is given).
+ *   The function is passed two parameters: 1. the DataTables settings object
+ *   for the table in question and 2. the index of that table in the current
+ *   context. The execution scope of the function is the API instance.
+ * @returns {DataTable.Api} Returns a new API instance if a selector is given,
+ *   or the callback function returns information from each loop. The
+ *   information, if returned, is assigned to the API instance. Otherwise the
+ *   original API instance is returned for chaining.
+ */
+_api.register( 'tables()', function ( selector, fn ) {
+	// Argument shifting
+	if ( typeof selector === 'function' ) {
+		fn = selector;
+		selector = undefined;
+	}
+
+	var a = [];
+	var context = selector ?
+		_table_selector( selector, this.context ) :
+		this.context;
+
+	if ( fn ) {
+		for ( var i=0, ien=context.length ; i<ien ; i++ ) {
+			var ret = fn.call( this, context[i], i );
+			if ( ret !== undefined ) {
+				a.push( ret );
+			}
+		}
+	}
+
+	// A new instance is created if there was a selector specified, or if
+	// data was returned from the callback
+	var api = selector || a.length ?
+		new _api( context, a ) :
+		this;
+
+	return api;
+} );
+
+
+/**
+ * Get the DOM nodes for the `table` elements from the current API context.
+ * @return {DataTable.Api} New Api instance containing the DOM nodes for the
+ *   tables.
+ */
+_api.register( 'tables().nodes()', function () {
+	return this.tables( function ( settings, i ) {
+		return settings.nTable;
+	} );
+} );
+
+
+}());
+